@turnkey/core 1.0.0 → 1.1.0

package/dist/__clients__/core.mjs

@@ -1,7 +1,8 @@
 import { TurnkeySDKClientBase } from '../__generated__/sdk-client-base.mjs';
 import { TurnkeyErrorCodes, TurnkeyError, TurnkeyNetworkError, AuthAction } from '@turnkey/sdk-types';
-import { SessionKey, DEFAULT_SESSION_EXPIRATION_IN_SECONDS, StamperType, WalletSource, Chain, FilterType, OtpTypeToFilterTypeMap, OtpType, Curve, SignIntent } from '../__types__/base.mjs';
-import { withTurnkeyErrorHandling, isValidPasskeyName, isWeb, isReactNative, buildSignUpBody, findWalletProviderFromAddress, addressFromPublicKey, getCurveTypeFromProvider, getPublicKeyFromStampHeader, toExternalTimestamp, getAuthenticatorAddresses, isEthereumProvider, isSolanaProvider, getHashFunction, getEncodingType, getEncodedMessage, splitSignature, broadcastTransaction, getPolicySignature, googleISS, isWalletAccountArray, generateWalletAccountsFromAddressFormat } from '../utils.mjs';
+import { SessionKey, DEFAULT_SESSION_EXPIRATION_IN_SECONDS, StamperType, FilterType, OtpTypeToFilterTypeMap, OtpType } from '../__types__/auth.mjs';
+import { WalletSource, Chain, Curve, SignIntent } from '../__types__/external-wallets.mjs';
+import { withTurnkeyErrorHandling, isValidPasskeyName, isWeb, isReactNative, buildSignUpBody, findWalletProviderFromAddress, addressFromPublicKey, getCurveTypeFromProvider, getPublicKeyFromStampHeader, mapAccountsToWallet, toExternalTimestamp, getAuthenticatorAddresses, isEthereumProvider, isSolanaProvider, getActiveSessionOrThrowIfRequired, getHashFunction, getEncodingType, getEncodedMessage, splitSignature, broadcastTransaction, getPolicySignature, googleISS, isWalletAccountArray, generateWalletAccountsFromAddressFormat } from '../utils.mjs';
 import { createStorageManager } from '../__storage__/base.mjs';
 import { CrossPlatformApiKeyStamper } from '../__stampers__/api/base.mjs';
 import { CrossPlatformPasskeyStamper } from '../__stampers__/passkey/base.mjs';
@@ -22,29 +23,30 @@ class TurnkeyClient {
          * - The resulting attestation and challenge can be used to register the passkey with Turnkey.
          *
          * @param params.name - display name for the passkey (defaults to a generated name based on the current timestamp).
-         * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          * @param params.challenge - challenge string to use for passkey registration. If not provided, a new challenge will be generated.
-         * @returns A promise that resolves to an object containing:
-         *   - attestation: attestation object returned from the passkey creation process.
-         *   - encodedChallenge: encoded challenge string used for passkey registration.
+         * @returns A promise that resolves to {@link CreatePasskeyResult}
          * @throws {TurnkeyError} If there is an error during passkey creation, or if the platform is unsupported.
          */
         this.createPasskey = async (params) => {
+            const { name: nameFromParams, challenge } = params || {};
             return withTurnkeyErrorHandling(async () => {
-                const name = isValidPasskeyName(params?.name || `passkey-${Date.now()}`);
+                if (!this.passkeyStamper) {
+                    throw new TurnkeyError("Passkey stamper is not initialized", TurnkeyErrorCodes.INTERNAL_ERROR);
+                }
+                const name = isValidPasskeyName(nameFromParams || `passkey-${Date.now()}`);
                 let passkey;
                 if (isWeb()) {
-                    const res = await this.passkeyStamper?.createWebPasskey({
+                    const res = await this.passkeyStamper.createWebPasskey({
                         publicKey: {
                             user: {
                                 name,
                                 displayName: name,
                             },
-                            ...(params?.challenge && { challenge: params.challenge }),
+                            ...(challenge && { challenge }),
                         },
                     });
                     if (!res) {
-                        throw new TurnkeyError("Failed to create React Native passkey", TurnkeyErrorCodes.INTERNAL_ERROR);
+                        throw new TurnkeyError("Failed to create Web passkey", TurnkeyErrorCodes.INTERNAL_ERROR);
                     }
                     passkey = {
                         encodedChallenge: res?.encodedChallenge,
@@ -52,7 +54,7 @@ class TurnkeyClient {
                     };
                 }
                 else if (isReactNative()) {
-                    const res = await this.passkeyStamper?.createReactNativePasskey({
+                    const res = await this.passkeyStamper.createReactNativePasskey({
                         name,
                         displayName: name,
                     });
@@ -125,6 +127,7 @@ class TurnkeyClient {
          * @param params.publicKey - public key to use for authentication. If not provided, a new key pair will be generated.
          * @param params.sessionKey - session key to use for session creation (defaults to the default session key).
          * @param params.expirationSeconds - session expiration time in seconds (defaults to the configured default).
+         * @param params.organizationId - organization ID to target (defaults to the session's organization ID or the parent organization ID).
          * @returns A promise that resolves to a {@link PasskeyAuthResult}, which includes:
          *          - `sessionToken`: the signed JWT session token.
          *          - `credentialId`: an empty string.
@@ -142,7 +145,7 @@ class TurnkeyClient {
                 }
                 const sessionResponse = await this.httpClient.stampLogin({
                     publicKey: generatedPublicKey,
-                    organizationId: this.config.organizationId,
+                    organizationId: params?.organizationId ?? this.config.organizationId,
                     expirationSeconds,
                 }, StamperType.Passkey);
                 await this.storeSession({
@@ -193,13 +196,14 @@ class TurnkeyClient {
          * @param params.sessionKey - session key to use for storing the session (defaults to the default session key).
          * @param params.expirationSeconds - session expiration time in seconds (defaults to the configured default).
          * @param params.challenge - challenge string to use for passkey registration. If not provided, a new challenge will be generated.
+         * @param params.organizationId - organization ID to target (defaults to the session's organization ID or the parent organization ID).
          * @returns A promise that resolves to a {@link PasskeyAuthResult}, which includes:
          *          - `sessionToken`: the signed JWT session token.
          *          - `credentialId`: the credential ID associated with the passkey created.
          * @throws {TurnkeyError} If there is an error during passkey creation, sub-organization creation, or session storage.
          */
         this.signUpWithPasskey = async (params) => {
-            const { createSubOrgParams, passkeyDisplayName, sessionKey = SessionKey.DefaultSessionkey, expirationSeconds = DEFAULT_SESSION_EXPIRATION_IN_SECONDS, } = params || {};
+            const { createSubOrgParams, passkeyDisplayName, sessionKey = SessionKey.DefaultSessionkey, expirationSeconds = DEFAULT_SESSION_EXPIRATION_IN_SECONDS, organizationId, } = params || {};
             let generatedPublicKey = undefined;
             return withTurnkeyErrorHandling(async () => {
                 generatedPublicKey = await this.apiKeyStamper?.createKeyPair();
@@ -242,7 +246,7 @@ class TurnkeyClient {
                 this.apiKeyStamper?.setTemporaryPublicKey(generatedPublicKey);
                 const sessionResponse = await this.httpClient.stampLogin({
                     publicKey: newGeneratedKeyPair,
-                    organizationId: this.config.organizationId,
+                    organizationId: organizationId ?? this.config.organizationId,
                     expirationSeconds,
                 });
                 await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
@@ -299,7 +303,7 @@ class TurnkeyClient {
          * - Requires the wallet manager and its connector to be initialized.
          *
          * @param walletProvider - wallet provider to connect.
-         * @returns A promise that resolves once the wallet account is connected.
+         * @returns A promise that resolves with the connected wallet's address.
          * @throws {TurnkeyError} If the wallet manager is uninitialized or the connection fails.
          */
         this.connectWalletAccount = async (walletProvider) => {
@@ -307,7 +311,7 @@ class TurnkeyClient {
                 if (!this.walletManager?.connector) {
                     throw new TurnkeyError("Wallet connector is not initialized", TurnkeyErrorCodes.WALLET_MANAGER_COMPONENT_NOT_INITIALIZED);
                 }
-                await this.walletManager.connector.connectWalletAccount(walletProvider);
+                return await this.walletManager.connector.connectWalletAccount(walletProvider);
             }, {
                 errorMessage: "Unable to connect wallet account",
                 errorCode: TurnkeyErrorCodes.CONNECT_WALLET_ACCOUNT_ERROR,
@@ -386,6 +390,7 @@ class TurnkeyClient {
          * @param params.publicKey - optional public key to associate with the session (generated if not provided).
          * @param params.sessionKey - optional key to store the session under (defaults to the default session key).
          * @param params.expirationSeconds - optional session expiration time in seconds (defaults to the configured default).
+         * @param params.organizationId - organization ID to target (defaults to the session's organization ID or the parent organization ID).
          * @returns A promise that resolves to a {@link WalletAuthResult}, which includes:
          *          - `sessionToken`: the signed JWT session token.
          *          - `address`: the authenticated wallet address.
@@ -406,7 +411,7 @@ class TurnkeyClient {
                 this.walletManager.stamper.setProvider(walletProvider.interfaceType, walletProvider);
                 const sessionResponse = await this.httpClient.stampLogin({
                     publicKey,
-                    organizationId: this.config.organizationId,
+                    organizationId: params?.organizationId ?? this.config.organizationId,
                     expirationSeconds,
                 }, StamperType.Wallet);
                 await this.storeSession({
@@ -450,6 +455,7 @@ class TurnkeyClient {
          * @param params.createSubOrgParams - parameters for creating a sub-organization (e.g., authenticators, user metadata).
          * @param params.sessionKey - session key to use for storing the session (defaults to the default session key).
          * @param params.expirationSeconds - session expiration time in seconds (defaults to the configured default).
+         * @param params.organizationId - organization ID to target (defaults to the session's organization ID or the parent organization ID).
          * @returns A promise that resolves to a {@link WalletAuthResult}, which includes:
          *          - `sessionToken`: the signed JWT session token.
          *          - `address`: the authenticated wallet address.
@@ -541,6 +547,7 @@ class TurnkeyClient {
          * @param params.createSubOrgParams - optional parameters for creating a sub-organization (e.g., authenticators, user metadata).
          * @param params.sessionKey - session key to use for storing the session (defaults to the default session key).
          * @param params.expirationSeconds - session expiration time in seconds (defaults to the configured default).
+         * @param params.organizationId - organization ID to target (defaults to the session's organization ID or the parent organization ID).
          * @returns A promise that resolves to an object containing:
          *          - `sessionToken`: the signed JWT session token.
          *          - `address`: the authenticated wallet address.
@@ -572,6 +579,10 @@ class TurnkeyClient {
                     errorMessage: "Failed to create stamped request for wallet login",
                     errorCode: TurnkeyErrorCodes.WALLET_LOGIN_OR_SIGNUP_ERROR,
                     customErrorsByMessages: {
+                        "WalletConnect: The connection request has expired. Please scan the QR code again.": {
+                            message: "Your WalletConnect session expired. Please scan the QR code again.",
+                            code: TurnkeyErrorCodes.WALLET_CONNECT_EXPIRED,
+                        },
                         "Failed to sign the message": {
                             message: "Wallet auth was cancelled by the user.",
                             code: TurnkeyErrorCodes.CONNECT_WALLET_CANCELLED,
@@ -682,6 +693,7 @@ class TurnkeyClient {
          *
          * @param params.otpType - type of OTP to initialize (OtpType.Email or OtpType.Sms).
          * @param params.contact - contact information for the user (e.g., email address or phone number).
+         * @param params.organizationId - optional organization ID to target (defaults to the session's organization ID or the parent organization ID).
          * @returns A promise that resolves to the OTP ID required for verification.
          * @throws {TurnkeyError} If there is an error during the OTP initialization process or if the maximum number of OTPs has been reached.
          */
@@ -1100,36 +1112,61 @@ class TurnkeyClient {
          * - Returns both embedded and connected wallets in a single array, each with their respective accounts populated.
          * - Optionally allows stamping the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          *
-         * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          * @param params.walletProviders - array of wallet providers to use for fetching wallets.
+         * @param params.organizationId - organization ID to target (defaults to the session's organization ID).
+         * @param params.userId - user ID to target (defaults to the session's user ID).
+         * @param params.connectedOnly - if true, fetches only connected wallets; if false or undefined, fetches both embedded and connected wallets.
+         * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          * @returns A promise that resolves to an array of `Wallet` objects.
          * @throws {TurnkeyError} If no active session is found or if there is an error fetching wallets.
          */
         this.fetchWallets = async (params) => {
-            const { stampWith, walletProviders } = params || {};
+            const { walletProviders, organizationId: organizationIdFromParams, userId: userIdFromParams, connectedOnly, stampWith, } = params || {};
             const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            if (!session && !connectedOnly) {
+                throw new TurnkeyError("No active session found. Fetching embedded wallets requires a valid session. If you only need connected wallets, set the 'connectedOnly' parameter to true.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            }
+            // if `connectedOnly` is true, we need to make sure the walletManager is initialized
+            // or else we can't fetch connected wallets, and we throw an error
+            if (connectedOnly && !this.walletManager?.connector) {
+                throw new TurnkeyError("Wallet connector is not initialized", TurnkeyErrorCodes.WALLET_MANAGER_COMPONENT_NOT_INITIALIZED);
             }
             return withTurnkeyErrorHandling(async () => {
-                const res = await this.httpClient.getWallets({ organizationId: session.organizationId }, stampWith);
-                if (!res || !res.wallets) {
-                    throw new TurnkeyError("No wallets found in the response", TurnkeyErrorCodes.BAD_RESPONSE);
-                }
-                const embedded = await Promise.all(res.wallets.map(async (wallet) => {
-                    const embeddedWallet = {
-                        ...wallet,
-                        source: WalletSource.Embedded,
-                        accounts: [],
-                    };
-                    const accounts = await this.fetchWalletAccounts({
-                        wallet: embeddedWallet,
-                        ...(stampWith !== undefined && { stampWith }),
-                    });
-                    embeddedWallet.accounts = accounts;
-                    return embeddedWallet;
-                }));
+                let embedded = [];
+                // if connectedOnly is true, we skip fetching embedded wallets
+                if (!connectedOnly) {
+                    const organizationId = organizationIdFromParams || session?.organizationId;
+                    if (!organizationId) {
+                        throw new TurnkeyError("No organization ID provided and no active session found. Please log in first or pass in an organization ID.", TurnkeyErrorCodes.INVALID_REQUEST);
+                    }
+                    const userId = userIdFromParams || session?.userId;
+                    if (!userId) {
+                        throw new TurnkeyError("No user ID provided and no active session found. Please log in first or pass in a user ID.", TurnkeyErrorCodes.INVALID_REQUEST);
+                    }
+                    const res = await this.httpClient.getWalletAccounts({
+                        organizationId,
+                        includeWalletDetails: true,
+                    }, stampWith);
+                    const walletsRes = await this.httpClient.getWallets({
+                        organizationId,
+                    }, stampWith);
+                    if (!res || !res.accounts) {
+                        throw new TurnkeyError("No wallet accounts found in the response", TurnkeyErrorCodes.BAD_RESPONSE);
+                    }
+                    // create a map of walletId to EmbeddedWallet for easy lookup
+                    const walletMap = new Map(walletsRes.wallets.map((wallet) => [
+                        wallet.walletId,
+                        {
+                            ...wallet,
+                            source: WalletSource.Embedded,
+                            accounts: [],
+                        },
+                    ]));
+                    // map the accounts to their respective wallets
+                    embedded = mapAccountsToWallet(res.accounts, walletMap);
+                }
                 // if wallet connecting is disabled we return only embedded wallets
+                // this will never be hit if `connectedOnly` is true because of the check above
                 if (!this.walletManager?.connector)
                     return embedded;
                 const providers = walletProviders ?? (await this.fetchWalletProviders());
@@ -1143,7 +1180,11 @@ class TurnkeyClient {
                     group.push(provider);
                     groupedProviders.set(walletId, group);
                 }
-                const connected = (await Promise.all(Array.from(groupedProviders.entries()).map(async ([walletId, grouped]) => {
+                // has to be done in a for of loop so we can await each fetchWalletAccounts call individually
+                // otherwise await Promise.all would cause them all to fire at once breaking passkey only set ups
+                // (multiple wallet fetches at once causing "OperationError: A request is already pending.")
+                let connected = [];
+                for (const [walletId, grouped] of groupedProviders.entries()) {
                     const timestamp = toExternalTimestamp();
                     const wallet = {
                         source: WalletSource.Connected,
@@ -1159,10 +1200,16 @@ class TurnkeyClient {
                         wallet,
                         walletProviders: grouped,
                         ...(stampWith !== undefined && { stampWith }),
+                        ...(organizationIdFromParams !== undefined && {
+                            organizationId: organizationIdFromParams,
+                        }),
+                        ...(userIdFromParams !== undefined && { userId: userIdFromParams }),
                     });
                     wallet.accounts = accounts;
-                    return wallet;
-                }))).filter((wallet) => wallet.accounts.length > 0);
+                    if (wallet.accounts.length > 0) {
+                        connected.push(wallet);
+                    }
+                }
                 return [...embedded, ...connected];
             }, {
                 errorMessage: "Failed to fetch wallets",
@@ -1182,22 +1229,30 @@ class TurnkeyClient {
          * @param params.walletProviders - list of wallet providers to filter by (used for connected wallets).
          * @param params.paginationOptions - pagination options for embedded wallets.
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to target (defaults to the session's organization ID).
+         * @param params.userId - user ID to target (defaults to the session's user ID).
+         *
          * @returns A promise that resolves to an array of `v1WalletAccount` objects.
          * @throws {TurnkeyError} If no active session is found or if there is an error fetching wallet accounts.
          */
         this.fetchWalletAccounts = async (params) => {
             const { wallet, stampWith, walletProviders, paginationOptions } = params;
             const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
-            }
+            const organizationId = params?.organizationId || session?.organizationId;
+            const userId = params?.userId || session?.userId;
             return withTurnkeyErrorHandling(async () => {
                 // this is an embedded wallet so we fetch accounts from Turnkey
                 if (wallet.source === WalletSource.Embedded) {
                     const embedded = [];
+                    if (!organizationId) {
+                        throw new TurnkeyError("No organization ID provided and no active session found. Please log in first or pass in an organization ID.", TurnkeyErrorCodes.INVALID_REQUEST);
+                    }
+                    if (!userId) {
+                        throw new TurnkeyError("No user ID provided and no active session found. Please log in first or pass in a user ID.", TurnkeyErrorCodes.INVALID_REQUEST);
+                    }
                     const res = await this.httpClient.getWalletAccounts({
                         walletId: wallet.walletId,
-                        organizationId: session.organizationId,
+                        organizationId,
                         paginationOptions: paginationOptions || { limit: "100" },
                     }, stampWith);
                     if (!res || !res.accounts) {
@@ -1228,17 +1283,26 @@ class TurnkeyClient {
                 const matching = providers.filter((p) => p.info?.name?.toLowerCase().replace(/\s+/g, "-") ===
                     wallet.walletId && p.connectedAddresses.length > 0);
                 const sign = this.walletManager.connector.sign.bind(this.walletManager.connector);
-                const user = await this.fetchUser({
-                    stampWith,
-                });
-                const { ethereum: ethereumAddresses, solana: solanaAddresses } = getAuthenticatorAddresses(user);
+                let ethereumAddresses = [];
+                let solanaAddresses = [];
+                // we only fetch the user if we have to the organizationId and userId
+                // if not that means `isAuthenticator` will always be false
+                if (organizationId && userId) {
+                    const user = await this.fetchUser({
+                        userId,
+                        organizationId,
+                        stampWith,
+                    });
+                    ({ ethereum: ethereumAddresses, solana: solanaAddresses } =
+                        getAuthenticatorAddresses(user));
+                }
                 for (const provider of matching) {
                     const timestamp = toExternalTimestamp();
                     for (const address of provider.connectedAddresses) {
                         if (isEthereumProvider(provider)) {
                             const evmAccount = {
                                 walletAccountId: `${wallet.walletId}-${provider.interfaceType}-${address}`,
-                                organizationId: session.organizationId,
+                                organizationId: organizationId ?? "",
                                 walletId: wallet.walletId,
                                 pathFormat: "PATH_FORMAT_BIP32",
                                 path: WalletSource.Connected,
@@ -1260,7 +1324,7 @@ class TurnkeyClient {
                         if (isSolanaProvider(provider)) {
                             const solAccount = {
                                 walletAccountId: `${wallet.walletId}-${provider.interfaceType}-${address}`,
-                                organizationId: session.organizationId,
+                                organizationId: organizationId ?? "",
                                 walletId: wallet.walletId,
                                 pathFormat: "PATH_FORMAT_BIP32",
                                 path: WalletSource.Connected,
@@ -1296,17 +1360,19 @@ class TurnkeyClient {
          * - Supports stamping the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          *
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to target (defaults to the session's organization ID).
          * @returns A promise that resolves to an array of `v1PrivateKey` objects.
          * @throws {TurnkeyError} If no active session is found or if there is an error fetching private keys.
          */
         this.fetchPrivateKeys = async (params) => {
             const { stampWith } = params || {};
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const organizationId = params?.organizationId || session?.organizationId;
+            if (!organizationId) {
+                throw new TurnkeyError("No organization ID provided and no active session found. Please log in first or pass in an organization ID.", TurnkeyErrorCodes.INVALID_REQUEST);
             }
             return withTurnkeyErrorHandling(async () => {
-                const res = await this.httpClient.getPrivateKeys({ organizationId: session.organizationId }, stampWith);
+                const res = await this.httpClient.getPrivateKeys({ organizationId }, stampWith);
                 if (!res) {
                     throw new TurnkeyError("Failed to fetch private keys", TurnkeyErrorCodes.BAD_RESPONSE);
                 }
@@ -1319,33 +1385,43 @@ class TurnkeyClient {
         /**
          * Signs a message using the specified wallet account.
          *
-         * - Supports both embedded and connected wallets.
-         * - For **connected wallets**:
+         * Behavior differs depending on the wallet type:
+         *
+         * - **Connected wallets**
          *   - Delegates signing to the wallet provider’s native signing method.
-         *   - **Important:** For Ethereum wallets (e.g., MetaMask), signatures follow [EIP-191](https://eips.ethereum.org/EIPS/eip-191).
-         *     The message is automatically prefixed with `"\x19Ethereum Signed Message:\n" + message length`
-         *     before signing. As a result, this signature **cannot be used as a raw transaction signature**
-         *     or broadcast on-chain.
-         * - For **embedded wallets**, uses the Turnkey API to sign the message directly.
-         * - Automatically handles message encoding and hashing based on the wallet account’s address format,
+         *   - *Ethereum*: signatures always follow [EIP-191](https://eips.ethereum.org/EIPS/eip-191).
+         *     - The wallet automatically prefixes messages with
+         *       `"\x19Ethereum Signed Message:\n" + message length` before signing.
+         *     - As a result, these signatures cannot be used as raw transaction signatures or broadcast on-chain.
+         *     - If `addEthereumPrefix` is set to `false`, an error is thrown because connected Ethereum wallets always prefix.
+         *   - *Other chains*: follows the native connected wallet behavior.
+         *
+         * - **Embedded wallets**
+         *   - Uses the Turnkey API to sign the message directly.
+         *   - Supports optional `addEthereumPrefix`:
+         *     - If `true` (default for Ethereum), the message is prefixed before signing.
+         *     - If `false`, the raw message is signed without any prefix.
+         *
+         * Additional details:
+         * - Automatically handles encoding and hashing based on the wallet account’s address format,
          *   unless explicitly overridden.
+         * - Optionally allows stamping with a specific stamper
+         *   (`StamperType.Passkey`, `StamperType.ApiKey`, or `StamperType.Wallet`).
          *
-         * @param params.message - message to sign.
+         * @param params.message - plaintext (UTF-8) message to sign.
          * @param params.walletAccount - wallet account to use for signing.
-         * @param params.encoding - override for the payload encoding (defaults to the encoding appropriate for the address type).
-         * @param params.hashFunction - override for the hash function (defaults to the hash function appropriate for the address type).
-         * @param params.stampWith - stamper to tag the signing request (e.g., Passkey, ApiKey, or Wallet).
-         * @param params.addEthereumPrefix - whether to prefix the message with Ethereum's `"\x19Ethereum Signed Message:\n"` string.
-         *   - If `true` (default for Ethereum), the message is prefixed before signing.
-         *   - If `false`:
-         *     - Connected wallets will throw an error because they always prefix automatically.
-         *     - Embedded wallets will sign the raw message without any prefix.
-         *
-         * @returns A promise resolving to a `v1SignRawPayloadResult` containing the signature and metadata.
-         * @throws {TurnkeyError} If signing fails, if the wallet account does not support signing, or if the response is invalid.
+         * @param params.encoding - override for payload encoding (defaults to the encoding appropriate for the address format).
+         * @param params.hashFunction - override for hash function (defaults to the function appropriate for the address format).
+         * @param params.stampWith - optional stamper for the signing request.
+         * @param params.addEthereumPrefix - whether to prefix the message with Ethereum’s
+         *   `"\x19Ethereum Signed Message:\n"` string (default: `true` for Ethereum).
+         * @param params.organizationId - organization ID to target (defaults to the session's organization ID).
+         *
+         * @returns A promise that resolves to a `v1SignRawPayloadResult` containing the signature and metadata.
+         * @throws {TurnkeyError} If signing fails, the wallet type does not support message signing, or the response is invalid.
          */
         this.signMessage = async (params) => {
-            const { message, walletAccount, stampWith, addEthereumPrefix } = params;
+            const { message, walletAccount, stampWith, addEthereumPrefix, organizationId, } = params;
             const hashFunction = params.hashFunction || getHashFunction(walletAccount.addressFormat);
             const payloadEncoding = params.encoding || getEncodingType(walletAccount.addressFormat);
             return withTurnkeyErrorHandling(async () => {
@@ -1357,23 +1433,29 @@ class TurnkeyClient {
                     }
                     let encodedMessage = message;
                     if (isEthereum) {
-                        encodedMessage = getEncodedMessage(walletAccount.addressFormat, message);
+                        const msgBytes = toUtf8Bytes(message);
+                        encodedMessage = getEncodedMessage(payloadEncoding, msgBytes);
                     }
                     const sigHex = await walletAccount.signMessage(encodedMessage);
                     return splitSignature(sigHex, walletAccount.addressFormat);
                 }
                 // this is an embedded wallet
-                let messageToEncode = message;
+                let msgBytes = toUtf8Bytes(message);
                 if (addEthereumPrefix && isEthereum) {
-                    const prefix = `\x19Ethereum Signed Message:\n${toUtf8Bytes(message).length}`;
-                    messageToEncode = prefix + message;
-                }
-                const encodedMessage = getEncodedMessage(walletAccount.addressFormat, messageToEncode);
+                    const prefix = `\x19Ethereum Signed Message:\n${msgBytes.length}`;
+                    const prefixBytes = toUtf8Bytes(prefix);
+                    const combined = new Uint8Array(prefixBytes.length + msgBytes.length);
+                    combined.set(prefixBytes, 0);
+                    combined.set(msgBytes, prefixBytes.length);
+                    msgBytes = combined;
+                }
+                const encodedMessage = getEncodedMessage(payloadEncoding, msgBytes);
                 const response = await this.httpClient.signRawPayload({
                     signWith: walletAccount.address,
                     payload: encodedMessage,
                     encoding: payloadEncoding,
                     hashFunction,
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 if (response.activity.failure) {
                     throw new TurnkeyError("Failed to sign message, no signed payload returned", TurnkeyErrorCodes.SIGN_MESSAGE_ERROR);
@@ -1388,21 +1470,29 @@ class TurnkeyClient {
         /**
          * Signs a transaction using the specified wallet account.
          *
-         * - This function signs a blockchain transaction using the provided wallet address and transaction data.
-         * - Supports all Turnkey-supported blockchain networks (e.g., Ethereum, Solana, Tron).
-         * - Automatically determines the appropriate signing method based on the transaction type.
-         * - Delegates signing to the Turnkey API, which returns the signed transaction and related metadata.
-         * - Optionally allows stamping the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * Behavior differs depending on the type of wallet:
+         *
+         * - **Connected wallets**
+         *   - Ethereum: does not support raw transaction signing. Calling this function will throw an error instructing you to use `signAndSendTransaction` instead.
+         *   - Solana: supports raw transaction signing via the connected wallet provider.
+         *   - Other chains: not supported; will throw an error.
          *
-         * @param params.walletAccount - wallet account to use for signing the transaction.
-         * @param params.unsignedTransaction - unsigned transaction data (serialized as a string) to be signed.
+         * - **Embedded wallets**
+         *   - Delegates signing to the Turnkey API, which returns the signed transaction.
+         *   - Supports all Turnkey-supported transaction types (e.g., Ethereum, Solana, Tron).
+         *   - Optionally allows stamping with a specific stamper (`StamperType.Passkey`, `StamperType.ApiKey`, or `StamperType.Wallet`).
+         *
+         * @param params.walletAccount - wallet account to use for signing.
+         * @param params.unsignedTransaction - unsigned transaction data as a serialized
+         *   string in the canonical encoding for the given `transactionType`.
          * @param params.transactionType - type of transaction (e.g., "TRANSACTION_TYPE_ETHEREUM", "TRANSACTION_TYPE_SOLANA", "TRANSACTION_TYPE_TRON").
-         * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
-         * @returns A promise that resolves to a `TSignTransactionResponse` object containing the signed transaction and any additional signing metadata.
-         * @throws {TurnkeyError} If there is an error signing the transaction or if the response is invalid.
+         * @param params.stampWith - stamper to use for signing (`StamperType.Passkey`, `StamperType.ApiKey`, or `StamperType.Wallet`).
+         * @param params.organizationId - organization ID to target (defaults to the session's organization ID).
+         * @returns A promise that resolves to the signed transaction string.
+         * @throws {TurnkeyError} If the wallet type is unsupported, signing fails, or the response is invalid.
          */
         this.signTransaction = async (params) => {
-            const { walletAccount, unsignedTransaction, transactionType, stampWith } = params;
+            const { walletAccount, unsignedTransaction, transactionType, stampWith, organizationId, } = params;
             return withTurnkeyErrorHandling(async () => {
                 if (walletAccount.source === WalletSource.Connected) {
                     switch (walletAccount.chainInfo.namespace) {
@@ -1421,6 +1511,7 @@ class TurnkeyClient {
                     signWith: walletAccount.address,
                     unsignedTransaction,
                     type: transactionType,
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 return signTransaction.signedTransaction;
             }, {
@@ -1431,25 +1522,32 @@ class TurnkeyClient {
         /**
          * Signs and broadcasts a transaction using the specified wallet account.
          *
-         * - For **connected wallets**:
-         *   - Calls the wallet’s native `signAndSendTransaction` method.
-         *   - Does **not** require an `rpcUrl`.
+         * Behavior differs depending on the type of wallet:
+         *
+         * - **Connected wallets**
+         *   - *Ethereum*: delegates to the wallet’s native `signAndSendTransaction` method.
+         *     - Does **not** require an `rpcUrl` (the wallet handles broadcasting).
+         *   - *Solana*: signs the transaction locally with the connected wallet, but requires an `rpcUrl` to broadcast it.
+         *   - Other chains: not supported; will throw an error.
          *
-         * - For **embedded wallets**:
+         * - **Embedded wallets**
          *   - Signs the transaction using the Turnkey API.
-         *   - Requires an `rpcUrl` to broadcast the transaction.
-         *   - Broadcasts the transaction using a JSON-RPC client.
-         *
-         * @param params.walletAccount - wallet account to use for signing and sending.
-         * @param params.unsignedTransaction - unsigned transaction (serialized string).
-         * @param params.transactionType - transaction type (e.g., "TRANSACTION_TYPE_SOLANA").
-         * @param params.rpcUrl - required for embedded wallets to broadcast the signed transaction.
-         * @param params.stampWith - optional stamper to tag the signing request.
+         *   - Requires an `rpcUrl` to broadcast the signed transaction, since Turnkey does not broadcast directly.
+         *   - Broadcasts the transaction using a JSON-RPC client and returns the resulting transaction hash/signature.
+         *   - Optionally allows stamping with a specific stamper (`StamperType.Passkey`, `StamperType.ApiKey`, or `StamperType.Wallet`).
+         *
+         * @param params.walletAccount - wallet account to use for signing and broadcasting.
+         * @param params.unsignedTransaction - unsigned transaction data as a serialized
+         *   string in the canonical encoding for the given `transactionType`.
+         * @param params.transactionType - type of transaction (e.g., `"TRANSACTION_TYPE_SOLANA"`, `"TRANSACTION_TYPE_ETHEREUM"`).
+         * @param params.rpcUrl - JSON-RPC endpoint used for broadcasting (required for Solana connected wallets and all embedded wallets).
+         * @param params.stampWith - optional stamper to use when signing (`StamperType.Passkey`, `StamperType.ApiKey`, or `StamperType.Wallet`).
+         * @param params.organizationId - **Only for Turnkey embedded wallets**: organization ID to target (defaults to the session's organization ID).
          * @returns A promise that resolves to a transaction signature or hash.
-         * @throws {TurnkeyError} If signing or broadcasting fails.
+         * @throws {TurnkeyError} If the wallet type is unsupported, or if signing/broadcasting fails.
          */
         this.signAndSendTransaction = async (params) => {
-            const { walletAccount, unsignedTransaction, transactionType, rpcUrl, stampWith, } = params;
+            const { walletAccount, unsignedTransaction, transactionType, rpcUrl, stampWith, organizationId, } = params;
             return withTurnkeyErrorHandling(async () => {
                 if (walletAccount.source === WalletSource.Connected) {
                     // this is a connected wallet account
@@ -1484,6 +1582,7 @@ class TurnkeyClient {
                     signWith: walletAccount.address,
                     unsignedTransaction,
                     type: transactionType,
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 const signedTx = signTransactionResponse.signedTransaction;
                 const txHash = await broadcastTransaction({
@@ -1513,16 +1612,16 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If there is no active session, if there is no userId, or if there is an error fetching user details.
          */
         this.fetchUser = async (params) => {
-            const { stampWith } = params || {};
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
-            }
-            const userId = params?.userId || session.userId;
+            const { organizationId: organizationIdFromParams, userId: userIdFromParams, stampWith, } = params || {};
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const userId = userIdFromParams || session?.userId;
             if (!userId) {
                 throw new TurnkeyError("User ID must be provided to fetch user", TurnkeyErrorCodes.INVALID_REQUEST);
             }
-            const organizationId = params?.organizationId || session.organizationId;
+            const organizationId = organizationIdFromParams || session?.organizationId;
+            if (!organizationId) {
+                throw new TurnkeyError("Organization ID must be provided to fetch user", TurnkeyErrorCodes.INVALID_REQUEST);
+            }
             return withTurnkeyErrorHandling(async () => {
                 const userResponse = await this.httpClient.getUser({ organizationId, userId }, stampWith);
                 if (!userResponse || !userResponse.user) {
@@ -1545,24 +1644,26 @@ class TurnkeyClient {
          * @param params.publicKey - the P-256 public key to use for lookup and creation.
          * @param params.createParams.userName - optional username to assign if creating a new user (defaults to `"Public Key User"`).
          * @param params.createParams.apiKeyName - optional API key name to assign if creating a new API key (defaults to `public-key-user-${publicKey}`).
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
+         * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          * @returns A promise that resolves to the existing or newly created {@link v1User}.
          * @throws {TurnkeyError} If there is no active session, if the input is invalid, if user retrieval fails, or if user creation fails.
          */
         this.fetchOrCreateP256ApiKeyUser = async (params) => {
-            const { publicKey, createParams } = params;
+            const { publicKey, createParams, stampWith, organizationId: organizationIdFromParams, } = params;
             return withTurnkeyErrorHandling(async () => {
-                const session = await this.storageManager.getActiveSession();
-                if (!session) {
-                    throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+                const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+                const organizationId = organizationIdFromParams || session?.organizationId;
+                if (!organizationId) {
+                    throw new TurnkeyError("Organization ID is required to fetch or create P-256 API key user.", TurnkeyErrorCodes.INVALID_REQUEST);
                 }
-                const organizationId = session.organizationId;
                 // we validate their input
                 if (!publicKey?.trim()) {
                     throw new TurnkeyError("'publicKey' is required and cannot be empty.", TurnkeyErrorCodes.INVALID_REQUEST);
                 }
                 const usersResponse = await this.httpClient.getUsers({
                     organizationId,
-                });
+                }, stampWith);
                 if (!usersResponse || !usersResponse.users) {
                     throw new TurnkeyError("No users found in the response", TurnkeyErrorCodes.BAD_RESPONSE);
                 }
@@ -1592,7 +1693,7 @@ class TurnkeyClient {
                             oauthProviders: [],
                         },
                     ],
-                });
+                }, stampWith);
                 if (!createUserResp?.userIds ||
                     createUserResp.userIds.length === 0 ||
                     !createUserResp.userIds[0]) {
@@ -1602,6 +1703,7 @@ class TurnkeyClient {
                 return await this.fetchUser({
                     organizationId,
                     userId: newUserId,
+                    stampWith,
                 });
             }, {
                 errorMessage: "Failed to get or create P-256 API key user",
@@ -1617,6 +1719,8 @@ class TurnkeyClient {
          *   - If it does not exist, it is created and returned with its new `policyId`.
          *
          * @param params.policies - the list of policies to fetch or create.
+         * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
          * @returns A promise that resolves to an array of objects, each containing:
          *          - `policyId`: the unique identifier of the policy.
          *          - `policyName`: human-readable name of the policy.
@@ -1628,20 +1732,20 @@ class TurnkeyClient {
          *                        if fetching policies fails, or if creating policies fails.
          */
         this.fetchOrCreatePolicies = async (params) => {
-            const { policies } = params;
+            const { policies, stampWith } = params;
             return await withTurnkeyErrorHandling(async () => {
-                const session = await this.storageManager.getActiveSession();
-                if (!session) {
-                    throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
-                }
+                const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
                 if (!Array.isArray(policies) || policies.length === 0) {
                     throw new TurnkeyError("'policies' must be a non-empty array of policy definitions.", TurnkeyErrorCodes.INVALID_REQUEST);
                 }
-                const organizationId = session.organizationId;
+                const organizationId = params?.organizationId ?? session?.organizationId;
+                if (!organizationId) {
+                    throw new TurnkeyError("Organization ID is required to fetch or create policies.", TurnkeyErrorCodes.INVALID_REQUEST);
+                }
                 // we first fetch existing policies
                 const existingPoliciesResponse = await this.httpClient.getPolicies({
                     organizationId,
-                });
+                }, stampWith);
                 const existingPolicies = existingPoliciesResponse.policies || [];
                 // we create a map of existing policies by their signature
                 // where the policySignature maps to its policyId
@@ -1674,10 +1778,10 @@ class TurnkeyClient {
                 const createPoliciesResponse = await this.httpClient.createPolicies({
                     organizationId,
                     policies: missingPolicies,
-                });
+                }, stampWith);
                 // assign returned IDs back to the missing ones in order
                 if (!createPoliciesResponse || !createPoliciesResponse.policyIds) {
-                    throw new TurnkeyError("Failed to create missing delegated access policies", TurnkeyErrorCodes.CREATE_POLICY_ERROR);
+                    throw new TurnkeyError("Failed to create missing policies", TurnkeyErrorCodes.CREATE_POLICY_ERROR);
                 }
                 const newlyCreatedPolicies = missingPolicies.map((p, idx) => ({
                     ...p,
@@ -1689,7 +1793,7 @@ class TurnkeyClient {
                 // which includes each of their respective IDs
                 return [...alreadyExistingPolicies, ...newlyCreatedPolicies];
             }, {
-                errorMessage: "Failed to get or create delegated access policies",
+                errorMessage: "Failed to get or create policies",
                 errorCode: TurnkeyErrorCodes.CREATE_USERS_ERROR,
             });
         };
@@ -1706,16 +1810,17 @@ class TurnkeyClient {
          * @param params.verificationToken - verification token from OTP email verification (required if verifying the email).
          * @param params.userId - user ID to update a specific user's email (defaults to the current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
          * @returns A promise that resolves to the userId of the updated user.
          * @throws {TurnkeyError} If there is no active session, if the userId is missing, or if there is an error updating or verifying the user email.
          */
         this.updateUserEmail = async (params) => {
-            const { verificationToken, email, stampWith } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { verificationToken, email, stampWith, organizationId } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const userId = params?.userId || session?.userId;
+            if (!userId) {
+                throw new TurnkeyError("User ID must be provided to update user email", TurnkeyErrorCodes.INVALID_REQUEST);
             }
-            const userId = params?.userId || session.userId;
             return withTurnkeyErrorHandling(async () => {
                 const existingUser = await this.httpClient.proxyGetAccount({
                     filterType: FilterType.Email,
@@ -1728,6 +1833,7 @@ class TurnkeyClient {
                     userId: userId,
                     userEmail: email,
                     ...(verificationToken && { verificationToken }),
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 if (!res || !res.userId) {
                     throw new TurnkeyError("No user ID found in the update user email response", TurnkeyErrorCodes.BAD_RESPONSE);
@@ -1748,20 +1854,22 @@ class TurnkeyClient {
          *
          * @param params.userId - user ID to remove a specific user's email address (defaults to the current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
          * @returns A promise that resolves to the userId of the user whose email was removed.
          * @throws {TurnkeyError} If there is no active session, if the userId is missing, or if there is an error removing the user email.
          */
         this.removeUserEmail = async (params) => {
-            const { stampWith } = params || {};
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
-            }
+            const { stampWith, organizationId } = params || {};
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
             return withTurnkeyErrorHandling(async () => {
-                const userId = params?.userId || session.userId;
+                const userId = params?.userId || session?.userId;
+                if (!userId) {
+                    throw new TurnkeyError("User ID must be provided to remove user email", TurnkeyErrorCodes.INVALID_REQUEST);
+                }
                 const res = await this.httpClient.updateUserEmail({
                     userId: userId,
                     userEmail: "",
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 if (!res || !res.userId) {
                     throw new TurnkeyError("No user ID found in the remove user email response", TurnkeyErrorCodes.BAD_RESPONSE);
@@ -1785,21 +1893,23 @@ class TurnkeyClient {
          * @param params.verificationToken - verification token from OTP phone verification (required if verifying the phone number).
          * @param params.userId - user ID to update a specific user's phone number (defaults to the current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
          * @returns A promise that resolves to the userId of the updated user.
          * @throws {TurnkeyError} If there is no active session, if the userId is missing, or if there is an error updating or verifying the user phone number.
          */
         this.updateUserPhoneNumber = async (params) => {
-            const { verificationToken, phoneNumber, stampWith } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { verificationToken, phoneNumber, stampWith, organizationId } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const userId = params?.userId || session?.userId;
+            if (!userId) {
+                throw new TurnkeyError("User ID must be provided to update user phone number", TurnkeyErrorCodes.INVALID_REQUEST);
             }
-            const userId = params?.userId || session.userId;
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.updateUserPhoneNumber({
                     userId,
                     userPhoneNumber: phoneNumber,
                     ...(verificationToken && { verificationToken }),
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 if (!res || !res.userId) {
                     throw new TurnkeyError("Failed to update user phone number", TurnkeyErrorCodes.UPDATE_USER_PHONE_NUMBER_ERROR);
@@ -1820,20 +1930,22 @@ class TurnkeyClient {
          *
          * @param params.userId - user ID to remove a specific user's phone number (defaults to the current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
          * @returns A promise that resolves to the userId of the user whose phone number was removed.
          * @throws {TurnkeyError} If there is no active session, if the userId is missing, or if there is an error removing the user phone number.
          */
         this.removeUserPhoneNumber = async (params) => {
-            const { stampWith } = params || {};
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { stampWith, organizationId } = params || {};
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const userId = params?.userId || session?.userId;
+            if (!userId) {
+                throw new TurnkeyError("User ID must be provided to remove user phone number", TurnkeyErrorCodes.INVALID_REQUEST);
             }
-            const userId = params?.userId || session.userId;
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.updateUserPhoneNumber({
                     userId,
                     userPhoneNumber: "",
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 if (!res || !res.userId) {
                     throw new TurnkeyError("Failed to remove user phone number", TurnkeyErrorCodes.UPDATE_USER_PHONE_NUMBER_ERROR);
@@ -1856,20 +1968,22 @@ class TurnkeyClient {
          * @param params.userName - new name to set for the user.
          * @param params.userId - user ID to update a specific user's name (defaults to the current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
          * @returns A promise that resolves to the userId of the updated user.
          * @throws {TurnkeyError} If there is no active session, if the userId is missing, or if there is an error updating the user name.
          */
         this.updateUserName = async (params) => {
-            const { userName, stampWith } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { userName, stampWith, organizationId } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const userId = params?.userId || session?.userId;
+            if (!userId) {
+                throw new TurnkeyError("User ID must be provided to update user name", TurnkeyErrorCodes.INVALID_REQUEST);
             }
-            const userId = params?.userId || session.userId;
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.updateUserName({
                     userId,
                     userName,
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 if (!res || !res.userId) {
                     throw new TurnkeyError("No user ID found in the update user name response", TurnkeyErrorCodes.BAD_RESPONSE);
@@ -1892,6 +2006,7 @@ class TurnkeyClient {
          *
          * @param params.providerName - name of the OAuth provider to add (e.g., "Google", "Apple").
          * @param params.oidcToken - OIDC token for the OAuth provider.
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
          * @param params.userId - user ID to add the provider for a specific user (defaults to current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          * @returns A promise that resolves to an array of provider IDs associated with the user.
@@ -1899,29 +2014,34 @@ class TurnkeyClient {
          */
         this.addOauthProvider = async (params) => {
             const { providerName, oidcToken, stampWith } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
-            }
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
             return withTurnkeyErrorHandling(async () => {
                 const accountRes = await this.httpClient.proxyGetAccount({
                     filterType: "OIDC_TOKEN",
                     filterValue: oidcToken,
                 });
                 if (!accountRes) {
-                    throw new TurnkeyError(`Account fetch failed}`, TurnkeyErrorCodes.ACCOUNT_FETCH_ERROR);
+                    throw new TurnkeyError(`Account fetch failed`, TurnkeyErrorCodes.ACCOUNT_FETCH_ERROR);
                 }
                 if (accountRes.organizationId) {
                     throw new TurnkeyError("Account already exists with this OIDC token", TurnkeyErrorCodes.ACCOUNT_ALREADY_EXISTS);
                 }
-                const userId = params?.userId || session.userId;
-                const { email: oidcEmail, iss } = jwtDecode(oidcToken) || {}; // Parse the oidc token so we can get the email. Pass it in to updateUser then call createOauthProviders. This will be verified by Turnkey.
+                const userId = params?.userId || session?.userId;
+                if (!userId) {
+                    throw new TurnkeyError("User ID must be provided to add OAuth provider", TurnkeyErrorCodes.INVALID_REQUEST);
+                }
+                const organizationId = params?.organizationId ?? session?.organizationId;
+                if (!organizationId) {
+                    throw new TurnkeyError("Organization ID is required to add OAuth provider", TurnkeyErrorCodes.INVALID_REQUEST);
+                }
+                // parse the oidc token so we can get the email. Pass it in to updateUser then call createOauthProviders. This will be verified by Turnkey.
+                const { email: oidcEmail, iss } = jwtDecode(oidcToken) || {};
                 if (iss === googleISS) {
                     const verifiedSuborg = await this.httpClient.proxyGetAccount({
                         filterType: "EMAIL",
                         filterValue: oidcEmail,
                     });
-                    const isVerified = verifiedSuborg.organizationId === session.organizationId;
+                    const isVerified = verifiedSuborg.organizationId === organizationId;
                     const user = await this.fetchUser({
                         userId,
                         stampWith,
@@ -1964,20 +2084,22 @@ class TurnkeyClient {
          * @param params.providerIds - IDs of the OAuth providers to remove.
          * @param params.userId - user ID to remove the provider for a specific user (defaults to the current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
          * @returns A promise that resolves to an array of provider IDs that were removed.
          * @throws {TurnkeyError} If there is no active session, if the userId is missing, or if there is an error removing the OAuth provider.
          */
         this.removeOauthProviders = async (params) => {
-            const { providerIds, stampWith } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { providerIds, stampWith, organizationId } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const userId = params?.userId || session?.userId;
+            if (!userId) {
+                throw new TurnkeyError("User ID must be provided to remove OAuth provider", TurnkeyErrorCodes.INVALID_REQUEST);
             }
-            const userId = params?.userId || session.userId;
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.deleteOauthProviders({
                     userId,
                     providerIds,
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 if (!res) {
                     throw new TurnkeyError("Failed to remove OAuth provider", TurnkeyErrorCodes.REMOVE_OAUTH_PROVIDER_ERROR);
@@ -2001,21 +2123,21 @@ class TurnkeyClient {
          * @param params.displayName - display name of the passkey (defaults to the value of `name`).
          * @param params.userId - user ID to add the passkey for a specific user (defaults to the current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
          * @returns A promise that resolves to an array of authenticator IDs for the newly added passkey(s).
          * @throws {TurnkeyError} If there is no active session, if passkey creation fails, or if there is an error adding the passkey.
          */
         this.addPasskey = async (params) => {
-            const { stampWith } = params || {};
+            const { stampWith, organizationId } = params || {};
             const name = params?.name || `Turnkey Passkey-${Date.now()}`;
             return withTurnkeyErrorHandling(async () => {
-                const session = await this.storageManager.getActiveSession();
-                if (!session) {
-                    throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+                const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+                const userId = params?.userId || session?.userId;
+                if (!userId) {
+                    throw new TurnkeyError("User ID must be provided to add passkey", TurnkeyErrorCodes.INVALID_REQUEST);
                 }
-                const userId = params?.userId || session.userId;
                 const { encodedChallenge, attestation } = await this.createPasskey({
                     name,
-                    ...(stampWith && { stampWith }),
                 });
                 if (!attestation || !encodedChallenge) {
                     throw new TurnkeyError("Failed to create passkey challenge and attestation", TurnkeyErrorCodes.CREATE_PASSKEY_ERROR);
@@ -2029,6 +2151,7 @@ class TurnkeyClient {
                             attestation,
                         },
                     ],
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 return res?.authenticatorIds || [];
             }, {
@@ -2048,20 +2171,22 @@ class TurnkeyClient {
          * @param params.authenticatorIds - IDs of the authenticators (passkeys) to remove.
          * @param params.userId - user ID to remove the passkeys for a specific user (defaults to the current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.organizationId - organization ID to specify the sub-organization (defaults to the current session's organizationId).
          * @returns A promise that resolves to an array of authenticator IDs that were removed.
          * @throws {TurnkeyError} If there is no active session, if the userId is missing, or if there is an error removing the passkeys.
          */
         this.removePasskeys = async (params) => {
-            const { authenticatorIds, stampWith } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { authenticatorIds, stampWith, organizationId } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const userId = params?.userId || session?.userId;
+            if (!userId) {
+                throw new TurnkeyError("User ID must be provided to remove passkey", TurnkeyErrorCodes.INVALID_REQUEST);
             }
-            const userId = params?.userId || session.userId;
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.deleteAuthenticators({
                     userId,
                     authenticatorIds,
+                    ...(organizationId && { organizationId }),
                 }, stampWith);
                 if (!res) {
                     throw new TurnkeyError("No response found in the remove passkey response", TurnkeyErrorCodes.REMOVE_PASSKEY_ERROR);
@@ -2092,10 +2217,11 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If there is no active session or if there is an error creating the wallet.
          */
         this.createWallet = async (params) => {
-            const { walletName, accounts, organizationId, mnemonicLength, stampWith } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { walletName, accounts, organizationId: organizationIdFromParams, mnemonicLength, stampWith, } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const organizationId = organizationIdFromParams || session?.organizationId;
+            if (!organizationId) {
+                throw new TurnkeyError("Organization ID must be provided to create wallet", TurnkeyErrorCodes.INVALID_REQUEST);
             }
             let walletAccounts = [];
             if (accounts && !isWalletAccountArray(accounts)) {
@@ -2111,7 +2237,7 @@ class TurnkeyClient {
             }
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.createWallet({
-                    organizationId: organizationId || session.organizationId,
+                    organizationId: organizationId,
                     walletName,
                     accounts: walletAccounts,
                     mnemonicLength: mnemonicLength || 12,
@@ -2143,10 +2269,11 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If there is no active session, if the wallet does not exist, or if there is an error creating the wallet accounts.
          */
         this.createWalletAccounts = async (params) => {
-            const { accounts, walletId, organizationId, stampWith } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { accounts, walletId, organizationId: organizationIdFromParams, stampWith, } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const organizationId = organizationIdFromParams || session?.organizationId;
+            if (!organizationId) {
+                throw new TurnkeyError("Organization ID must be provided to create wallet accounts", TurnkeyErrorCodes.INVALID_REQUEST);
             }
             return withTurnkeyErrorHandling(async () => {
                 let walletAccounts = [];
@@ -2154,7 +2281,7 @@ class TurnkeyClient {
                     // Query existing wallet accounts to avoid duplicates
                     const existingWalletAccounts = await this.httpClient.getWalletAccounts({
                         walletId,
-                        organizationId: organizationId || session.organizationId,
+                        organizationId: organizationId,
                         paginationOptions: { limit: "100" },
                     }, stampWith);
                     walletAccounts = generateWalletAccountsFromAddressFormat({
@@ -2166,7 +2293,7 @@ class TurnkeyClient {
                     walletAccounts = accounts;
                 }
                 const res = await this.httpClient.createWalletAccounts({
-                    organizationId: organizationId || session.organizationId,
+                    organizationId: organizationId,
                     walletId,
                     accounts: walletAccounts,
                 }, stampWith);
@@ -2197,16 +2324,17 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If there is no active session, if the targetPublicKey is missing, or if there is an error exporting the wallet.
          */
         this.exportWallet = async (params) => {
-            const { walletId, targetPublicKey, stampWith, organizationId } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { walletId, targetPublicKey, stampWith, organizationId: organizationIdFromParams, } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const organizationId = organizationIdFromParams || session?.organizationId;
+            if (!organizationId) {
+                throw new TurnkeyError("Organization ID must be provided to export wallet", TurnkeyErrorCodes.INVALID_REQUEST);
             }
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.exportWallet({
                     walletId,
                     targetPublicKey,
-                    organizationId: organizationId || session.organizationId,
+                    organizationId: organizationId,
                 }, stampWith);
                 if (!res.exportBundle) {
                     throw new TurnkeyError("No export bundle found in the response", TurnkeyErrorCodes.BAD_RESPONSE);
@@ -2234,16 +2362,17 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If there is no active session, if the targetPublicKey is missing, or if there is an error exporting the private key.
          */
         this.exportPrivateKey = async (params) => {
-            const { privateKeyId, targetPublicKey, stampWith, organizationId } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { privateKeyId, targetPublicKey, stampWith, organizationId: organizationIdFromParams, } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const organizationId = organizationIdFromParams || session?.organizationId;
+            if (!organizationId) {
+                throw new TurnkeyError("Organization ID must be provided to export private key", TurnkeyErrorCodes.INVALID_REQUEST);
             }
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.exportPrivateKey({
                     privateKeyId,
                     targetPublicKey,
-                    organizationId: organizationId || session.organizationId,
+                    organizationId: organizationId,
                 }, stampWith);
                 if (!res.exportBundle) {
                     throw new TurnkeyError("No export bundle found in the response", TurnkeyErrorCodes.BAD_RESPONSE);
@@ -2272,16 +2401,17 @@ class TurnkeyClient {
          *
          */
         this.exportWalletAccount = async (params) => {
-            const { address, targetPublicKey, stampWith, organizationId } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { address, targetPublicKey, stampWith, organizationId: organizationIdFromParams, } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const organizationId = organizationIdFromParams || session?.organizationId;
+            if (!organizationId) {
+                throw new TurnkeyError("Organization ID must be provided to export wallet account", TurnkeyErrorCodes.INVALID_REQUEST);
             }
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.exportWalletAccount({
                     address,
                     targetPublicKey,
-                    organizationId: organizationId || session.organizationId,
+                    organizationId: organizationId,
                 }, stampWith);
                 if (!res.exportBundle) {
                     throw new TurnkeyError("No export bundle found in the response", TurnkeyErrorCodes.BAD_RESPONSE);
@@ -2305,21 +2435,27 @@ class TurnkeyClient {
          * @param params.encryptedBundle - encrypted bundle containing the wallet seed phrase and metadata.
          * @param params.walletName - name of the wallet to create upon import.
          * @param params.accounts - array of account parameters to create in the imported wallet (defaults to standard Ethereum and Solana accounts).
+         * @param params.organizationId - organization ID to import the wallet under a specific sub-organization (wallet will be associated with the sub-organization).
          * @param params.userId - user ID to import the wallet for a specific user (defaults to the current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          * @returns A promise that resolves to the ID of the imported wallet.
          * @throws {TurnkeyError} If there is no active session, if the encrypted bundle is invalid, or if there is an error importing the wallet.
          */
         this.importWallet = async (params) => {
-            const { encryptedBundle, accounts, walletName, userId, stampWith } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { encryptedBundle, accounts, walletName, organizationId: organizationIdFromParams, userId: userIdFromParams, stampWith, } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const organizationId = organizationIdFromParams || session?.organizationId;
+            if (!organizationId) {
+                throw new TurnkeyError("Organization ID must be provided to import wallet", TurnkeyErrorCodes.INVALID_REQUEST);
+            }
+            const userId = userIdFromParams || session?.userId;
+            if (!userId) {
+                throw new TurnkeyError("User ID must be provided to import wallet", TurnkeyErrorCodes.INVALID_REQUEST);
             }
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.importWallet({
-                    organizationId: session.organizationId,
-                    userId: userId || session.userId,
+                    organizationId: organizationId,
+                    userId: userId,
                     encryptedBundle,
                     walletName,
                     accounts: accounts || [
@@ -2357,21 +2493,27 @@ class TurnkeyClient {
          * @param params.privateKeyName - name of the private key to create upon import.
          * @param params.curve - the cryptographic curve used to generate a given private key
          * @param params.addressFormat - address format of the private key to import.
+         * @param params.organizationId - organization ID to import the private key under a specific sub-organization (private key will be associated with the sub-organization).
          * @param params.userId - user ID to import the wallet for a specific user (defaults to the current session's userId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          * @returns A promise that resolves to the ID of the imported wallet.
          * @throws {TurnkeyError} If there is no active session, if the encrypted bundle is invalid, or if there is an error importing the wallet.
          */
         this.importPrivateKey = async (params) => {
-            const { encryptedBundle, privateKeyName, addressFormats, curve, userId, stampWith, } = params;
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            const { encryptedBundle, privateKeyName, addressFormats, curve, organizationId: organizationIdFromParams, userId: userIdFromParams, stampWith, } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const organizationId = organizationIdFromParams || session?.organizationId;
+            if (!organizationId) {
+                throw new TurnkeyError("Organization ID must be provided to import private key", TurnkeyErrorCodes.INVALID_REQUEST);
+            }
+            const userId = userIdFromParams || session?.userId;
+            if (!userId) {
+                throw new TurnkeyError("User ID must be provided to import private key", TurnkeyErrorCodes.INVALID_REQUEST);
             }
             return withTurnkeyErrorHandling(async () => {
                 const res = await this.httpClient.importPrivateKey({
-                    organizationId: session.organizationId,
-                    userId: userId || session.userId,
+                    organizationId,
+                    userId,
                     encryptedBundle,
                     privateKeyName,
                     curve,
@@ -2402,18 +2544,17 @@ class TurnkeyClient {
          * - Optionally allows stamping the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          *
          * @param params.deleteWithoutExport - flag to delete the sub-organization without requiring all wallets to be exported first (defaults to false).
+         * @param params.organizationId - organization ID to delete a specific sub-organization (defaults to the current session's organizationId).
          * @param params.stampWith - parameter to stamp the request with a specific stamper.
          * @returns A promise that resolves to a `TDeleteSubOrganizationResponse` object containing the result of the deletion.
          * @throws {TurnkeyError} If there is no active session or if there is an error deleting the sub-organization.
          */
         this.deleteSubOrganization = async (params) => {
-            const { deleteWithoutExport = false, stampWith } = params || {};
-            const session = await this.storageManager.getActiveSession();
-            if (!session) {
-                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
-            }
+            const { deleteWithoutExport = false, organizationId: organizationIdFromParams, stampWith, } = params || {};
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const organizationId = organizationIdFromParams || session?.organizationId;
             return withTurnkeyErrorHandling(async () => {
-                return await this.httpClient.deleteSubOrganization({ deleteWithoutExport }, stampWith);
+                return await this.httpClient.deleteSubOrganization({ deleteWithoutExport, ...(organizationId && { organizationId }) }, stampWith);
             }, {
                 errorMessage: "Failed to delete sub-organization",
                 errorCode: TurnkeyErrorCodes.DELETE_SUB_ORGANIZATION_ERROR,