@turnkey/core 1.14.0 → 2.0.0

package/dist/__clients__/core.mjs

@@ -1,8 +1,9 @@
 import { TurnkeySDKClientBase } from '../__generated__/sdk-client-base.mjs';
 import { TurnkeyErrorCodes, TurnkeyError, AuthAction } from '@turnkey/sdk-types';
 import { DEFAULT_SESSION_EXPIRATION_IN_SECONDS } from '../__types__/auth.mjs';
-import { SessionKey, StamperType, WalletSource, FilterType, OtpTypeToFilterTypeMap, OtpType, Curve, Chain, SignIntent } from '../__types__/enums.mjs';
-import { withTurnkeyErrorHandling, isValidPasskeyName, isWeb, isReactNative, buildSignUpBody, findWalletProviderFromAddress, getPublicKeyFromStampHeader, addressFromPublicKey, getCurveTypeFromProvider, getClientSignatureMessageForLogin, getClientSignatureMessageForSignup, getAuthenticatorAddresses, fetchAllWalletAccountsWithCursor, mapAccountsToWallet, toExternalTimestamp, isEthereumProvider, isSolanaProvider, getActiveSessionOrThrowIfRequired, getHashFunction, getEncodingType, getEncodedMessage, splitSignature, broadcastTransaction, getPolicySignature, googleISS, isWalletAccountArray, generateWalletAccountsFromAddressFormat } from '../utils.mjs';
+import { SessionKey, StamperType, WalletSource, FilterType, OtpType, OtpTypeToFilterTypeMap, Curve, Chain, SignIntent } from '../__types__/enums.mjs';
+import { withTurnkeyErrorHandling, isValidPasskeyName, isWeb, isReactNative, buildSignUpBody, findWalletProviderFromAddress, getPublicKeyFromStampHeader, addressFromPublicKey, getCurveTypeFromProvider, getClientSignatureMessageForLogin, getClientSignatureMessageForSignup, getAuthenticatorAddresses, fetchAllWalletAccountsWithCursor, mapAccountsToWallet, toExternalTimestamp, isEthereumProvider, isSolanaProvider, getActiveSessionOrThrowIfRequired, getHashFunction, getEncodingType, getEncodedMessage, splitSignature, broadcastTransaction, ERC20_TRANSFER_ABI, getPolicySignature, googleISS, isWalletAccountArray, generateWalletAccountsFromAddressFormat } from '../utils.mjs';
+import { encryptOtpCodeToBundle, verify } from '@turnkey/crypto';
 import { createStorageManager } from '../__storage__/base.mjs';
 import { CrossPlatformApiKeyStamper } from '../__stampers__/api/base.mjs';
 import { CrossPlatformPasskeyStamper } from '../__stampers__/passkey/base.mjs';
@@ -10,26 +11,68 @@ import { DEFAULT_ETHEREUM_ACCOUNTS, DEFAULT_SOLANA_ACCOUNTS } from '../turnkey-h
 import { jwtDecode } from 'jwt-decode';
 import { createWalletManager } from '../__wallet__/base.mjs';
 import { toUtf8Bytes } from 'ethers';
-import { verify } from '@turnkey/crypto';
 import { SignatureFormat } from '@turnkey/api-key-stamper';
 import { encodeFunctionData } from 'viem';
 
-const ERC20_TRANSFER_ABI = [
-    {
-        type: "function",
-        name: "transfer",
-        stateMutability: "nonpayable",
-        inputs: [
-            { name: "to", type: "address" },
-            { name: "amount", type: "uint256" },
-        ],
-        outputs: [{ name: "success", type: "bool" }],
-    },
-];
 class TurnkeyClient {
     constructor(config, 
     // Users can pass in their own stampers, or we will create them. Should we remove this?
     apiKeyStamper, passkeyStamper, walletManager) {
+        /**
+         * Overrides the API key stamper configuration.
+         *
+         * - Set `temporaryPublicKey` to a non-empty string to override the default API key.
+         * - Set `temporaryPublicKey` to an empty string ("") to clear the temporary key and restore default behavior.
+         * - Omit `temporaryPublicKey` to leave it unchanged.
+         * - Useful for dynamically changing the API key used for signing requests.
+         *
+         * @param params.temporaryPublicKey - temporary public key to set (non-empty string), clear (empty string), or leave unchanged (omit).
+         * @returns A promise that resolves when the stamper has been updated.
+         * @throws {TurnkeyError} If the API key stamper is not initialized or if there is an error updating it.
+         */
+        this.overrideApiKeyStamper = async (params) => {
+            return withTurnkeyErrorHandling(async () => {
+                if (!this.apiKeyStamper) {
+                    throw new TurnkeyError("API key stamper is not initialized", TurnkeyErrorCodes.INTERNAL_ERROR);
+                }
+                const { temporaryPublicKey } = params;
+                // Only process if temporaryPublicKey is explicitly passed
+                if (temporaryPublicKey !== undefined) {
+                    if (temporaryPublicKey === "") {
+                        this.apiKeyStamper.clearTemporaryPublicKey();
+                    }
+                    else {
+                        this.apiKeyStamper.setTemporaryPublicKey(temporaryPublicKey);
+                    }
+                }
+            }, {
+                errorMessage: "Failed to override API key stamper",
+                errorCode: TurnkeyErrorCodes.INITIALIZE_API_KEY_STAMPER_ERROR,
+            });
+        };
+        /**
+         * Overrides the passkey stamper with a new configuration.
+         *
+         * - This function updates the passkey stamper configuration without reinitializing the entire stamper.
+         * - Updates the stamper's configuration properties (e.g., allowCredentials, rpId, timeout, userVerification).
+         * - Useful for dynamically changing passkey configuration during runtime.
+         *
+         * @param params.config - new passkey stamper configuration to use.
+         * @returns A promise that resolves when the stamper configuration has been updated.
+         * @throws {TurnkeyError} If there is an error updating the stamper configuration or if the passkey stamper is not initialized.
+         */
+        this.overridePasskeyStamper = async (params) => {
+            const { config } = params;
+            return withTurnkeyErrorHandling(async () => {
+                if (!this.passkeyStamper) {
+                    throw new TurnkeyError("Passkey stamper is not initialized", TurnkeyErrorCodes.INTERNAL_ERROR);
+                }
+                this.passkeyStamper.updateConfig(config);
+            }, {
+                errorMessage: "Failed to override passkey stamper",
+                errorCode: TurnkeyErrorCodes.INITIALIZE_PASSKEY_STAMPER_ERROR,
+            });
+        };
         /**
          * Creates a new TurnkeySDKClientBase instance with the provided configuration.
          * This method is used internally to create the HTTP client for making API requests,
@@ -147,14 +190,14 @@ class TurnkeyClient {
                 if (params?.sessionKey) {
                     const session = await this.storageManager.getSession(params.sessionKey);
                     this.storageManager.clearSession(params.sessionKey);
-                    this.apiKeyStamper?.deleteKeyPair(session?.publicKey);
+                    await this.deleteApiKeyPair({ publicKey: session?.publicKey });
                 }
                 else {
                     const sessionKey = await this.storageManager.getActiveSessionKey();
                     const session = await this.storageManager.getActiveSession();
                     if (sessionKey) {
                         this.storageManager.clearSession(sessionKey);
-                        this.apiKeyStamper?.deleteKeyPair(session?.publicKey);
+                        await this.deleteApiKeyPair({ publicKey: session?.publicKey });
                     }
                     else {
                         throw new TurnkeyError("No active session found to log out from.", TurnkeyErrorCodes.NO_SESSION_FOUND);
@@ -178,18 +221,30 @@ class TurnkeyClient {
          * @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).
+         * @param params.allowCredentials - optional list of allowed credentials for passkey authentication. This allows you to restrict which passkeys can be used for login.
          * @returns A promise that resolves to a {@link PasskeyAuthResult}, which includes:
          *          - `sessionToken`: the signed JWT session token.
          *          - `credentialId`: an empty string.
          * @throws {TurnkeyError} If there is an error during the passkey login process or if the user cancels the passkey prompt.
          */
         this.loginWithPasskey = async (params) => {
-            let generatedPublicKey = undefined;
+            const shouldOverrideConfig = params?.allowCredentials && this.passkeyStamper;
+            const currentConfig = this.config.passkeyConfig;
+            const generatedPublicKey = params?.publicKey || (await this.createApiKeyPair());
             return await withTurnkeyErrorHandling(async () => {
-                generatedPublicKey =
-                    params?.publicKey || (await this.apiKeyStamper?.createKeyPair());
+                if (!this.passkeyStamper) {
+                    throw new TurnkeyError("Passkey stamper is not initialized", TurnkeyErrorCodes.INTERNAL_ERROR);
+                }
                 const sessionKey = params?.sessionKey || SessionKey.DefaultSessionkey;
                 const expirationSeconds = params?.expirationSeconds || DEFAULT_SESSION_EXPIRATION_IN_SECONDS;
+                if (shouldOverrideConfig) {
+                    // Override passkey stamper config to include allowCredentials
+                    const mergedConfig = {
+                        ...currentConfig,
+                        allowCredentials: params?.allowCredentials, // Can safely assert non-null due to check above
+                    };
+                    await this.overridePasskeyStamper({ config: mergedConfig });
+                }
                 if (!generatedPublicKey) {
                     throw new TurnkeyError("A publickey could not be found or generated.", TurnkeyErrorCodes.INTERNAL_ERROR);
                 }
@@ -202,7 +257,6 @@ class TurnkeyClient {
                     sessionToken: sessionResponse.session,
                     sessionKey,
                 });
-                generatedPublicKey = undefined; // Key pair was successfully used, set to null to prevent cleanup
                 return {
                     sessionToken: sessionResponse.session,
                     // TODO: can we return the credentialId here?
@@ -219,15 +273,23 @@ class TurnkeyClient {
                         code: TurnkeyErrorCodes.SELECT_PASSKEY_CANCELLED,
                     },
                 },
+                catchFn: async () => {
+                    try {
+                        await this.deleteApiKeyPair({ publicKey: generatedPublicKey });
+                    }
+                    catch (cleanupError) {
+                        throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
+                    }
+                },
             }, {
                 finallyFn: async () => {
-                    if (generatedPublicKey) {
-                        try {
-                            await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
-                        }
-                        catch (cleanupError) {
-                            throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
-                        }
+                    if (shouldOverrideConfig) {
+                        // we restore previous stamper after login attempt
+                        await this.overridePasskeyStamper({
+                            // we can assert this safely, since if this statement runs we are certian the passkey stamper
+                            // is initialized
+                            config: currentConfig,
+                        });
                     }
                 },
             });
@@ -246,17 +308,18 @@ class TurnkeyClient {
          * @param params.expirationSeconds - session expiration time in seconds (defaults to the configured default).
          * @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.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 { passkeyDisplayName, challenge, expirationSeconds = DEFAULT_SESSION_EXPIRATION_IN_SECONDS, createSubOrgParams, sessionKey = SessionKey.DefaultSessionkey, organizationId, } = params || {};
-            let generatedPublicKey = undefined;
+            const { passkeyDisplayName, challenge, expirationSeconds = DEFAULT_SESSION_EXPIRATION_IN_SECONDS, createSubOrgParams, sessionKey = SessionKey.DefaultSessionkey, } = params || {};
+            const generatedPublicKey = await this.createApiKeyPair();
             return withTurnkeyErrorHandling(async () => {
-                generatedPublicKey = await this.apiKeyStamper?.createKeyPair();
+                if (!this.passkeyStamper) {
+                    throw new TurnkeyError("Passkey stamper is not initialized", TurnkeyErrorCodes.INTERNAL_ERROR);
+                }
                 const passkeyName = passkeyDisplayName || `passkey-${Date.now()}`;
                 // A passkey will be created automatically when you call this function. The name is passed in
                 const passkey = await this.createPasskey({
@@ -288,25 +351,23 @@ class TurnkeyClient {
                         ],
                     },
                 });
-                const res = await this.httpClient.proxySignup(signUpBody);
+                const res = await this.httpClient.proxySignupV2(signUpBody);
                 if (!res) {
                     throw new TurnkeyError(`Sign up failed`, TurnkeyErrorCodes.PASSKEY_SIGNUP_AUTH_ERROR);
                 }
-                const newGeneratedKeyPair = await this.apiKeyStamper?.createKeyPair();
-                this.apiKeyStamper?.setTemporaryPublicKey(generatedPublicKey);
+                const newGeneratedKeyPair = await this.createApiKeyPair();
+                await this.overrideApiKeyStamper({
+                    temporaryPublicKey: generatedPublicKey,
+                });
                 const sessionResponse = await this.httpClient.stampLogin({
                     publicKey: newGeneratedKeyPair,
-                    organizationId: organizationId ?? this.config.organizationId,
+                    organizationId: res.organizationId,
                     expirationSeconds,
                 });
-                await Promise.all([
-                    this.apiKeyStamper?.deleteKeyPair(generatedPublicKey),
-                    this.storeSession({
-                        sessionToken: sessionResponse.session,
-                        sessionKey,
-                    }),
-                ]);
-                generatedPublicKey = undefined; // Key pair was successfully used, set to null to prevent cleanup
+                await this.storeSession({
+                    sessionToken: sessionResponse.session,
+                    sessionKey,
+                });
                 return {
                     sessionToken: sessionResponse.session,
                     appProofs: res.appProofs,
@@ -317,14 +378,12 @@ class TurnkeyClient {
                 errorMessage: "Failed to sign up with passkey",
             }, {
                 finallyFn: async () => {
-                    this.apiKeyStamper?.clearTemporaryPublicKey();
-                    if (generatedPublicKey) {
-                        try {
-                            await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
-                        }
-                        catch (cleanupError) {
-                            throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
-                        }
+                    try {
+                        await this.overrideApiKeyStamper({ temporaryPublicKey: "" });
+                        await this.deleteApiKeyPair({ publicKey: generatedPublicKey });
+                    }
+                    catch (cleanupError) {
+                        throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
                     }
                 },
             });
@@ -464,13 +523,11 @@ class TurnkeyClient {
         this.buildWalletLoginRequest = async (params) => {
             const { walletProvider, publicKey: providedPublicKey } = params;
             const expirationSeconds = params.expirationSeconds || DEFAULT_SESSION_EXPIRATION_IN_SECONDS;
-            let generatedPublicKey = undefined;
+            const futureSessionPublicKey = providedPublicKey ?? (await this.createApiKeyPair());
             return withTurnkeyErrorHandling(async () => {
                 if (!this.walletManager?.stamper) {
                     throw new TurnkeyError("Wallet stamper is not initialized", TurnkeyErrorCodes.WALLET_MANAGER_COMPONENT_NOT_INITIALIZED);
                 }
-                const futureSessionPublicKey = providedPublicKey ??
-                    (generatedPublicKey = await this.apiKeyStamper?.createKeyPair());
                 if (!futureSessionPublicKey) {
                     throw new TurnkeyError("Failed to find or generate a public key for building the wallet login request", TurnkeyErrorCodes.WALLET_BUILD_LOGIN_REQUEST_ERROR);
                 }
@@ -512,9 +569,12 @@ class TurnkeyClient {
                 errorCode: TurnkeyErrorCodes.WALLET_BUILD_LOGIN_REQUEST_ERROR,
                 errorMessage: "Failed to build wallet login request",
                 catchFn: async () => {
-                    if (generatedPublicKey) {
+                    // we only clean up the generated key pair if we created it here
+                    if (!providedPublicKey) {
                         try {
-                            await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
+                            await this.deleteApiKeyPair({
+                                publicKey: futureSessionPublicKey,
+                            });
                         }
                         catch (cleanupError) {
                             throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
@@ -599,7 +659,7 @@ class TurnkeyClient {
                         ],
                     },
                 });
-                const res = await this.httpClient.proxySignup(signUpBody);
+                const res = await this.httpClient.proxySignupV2(signUpBody);
                 if (!res) {
                     throw new TurnkeyError(`Sign up failed`, TurnkeyErrorCodes.WALLET_SIGNUP_AUTH_ERROR);
                 }
@@ -674,7 +734,7 @@ class TurnkeyClient {
                             ],
                         },
                     });
-                    signupRes = await this.httpClient.proxySignup(signUpBody);
+                    signupRes = await this.httpClient.proxySignupV2(signUpBody);
                     if (!signupRes) {
                         throw new TurnkeyError(`Sign up failed`, TurnkeyErrorCodes.WALLET_SIGNUP_AUTH_ERROR);
                     }
@@ -706,21 +766,29 @@ class TurnkeyClient {
          *
          * - This function initiates the OTP flow by sending a one-time password (OTP) code to the user's contact information (email address or phone number) via the auth proxy.
          * - Supports both email and SMS OTP types.
-         * - Returns an OTP ID that is required for subsequent OTP verification.
+         * - Returns an OTP ID and an encryption target bundle required for subsequent OTP verification.
+         * - The `otpEncryptionTargetBundle` must be used to encrypt the OTP code and a client-generated public key before calling `verifyOtp`.
          *
          * @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.
+         * @returns A promise that resolves to an {@link InitOtpResult}, which includes:
+         *          - `otpId`: the ID of the initiated OTP.
+         *          - `otpEncryptionTargetBundle`: the signed encryption target bundle for encrypting the OTP code.
          * @throws {TurnkeyError} If there is an error during the OTP initialization process or if the maximum number of OTPs has been reached.
          */
         this.initOtp = async (params) => {
             return withTurnkeyErrorHandling(async () => {
-                const initOtpRes = await this.httpClient.proxyInitOtp(params);
-                if (!initOtpRes || !initOtpRes.otpId) {
-                    throw new TurnkeyError("Failed to initialize OTP: otpId is missing", TurnkeyErrorCodes.INIT_OTP_ERROR);
+                const initOtpRes = await this.httpClient.proxyInitOtpV2(params);
+                if (!initOtpRes ||
+                    !initOtpRes.otpId ||
+                    !initOtpRes.otpEncryptionTargetBundle) {
+                    throw new TurnkeyError("Failed to initialize OTP: otpId or otpEncryptionTargetBundle is missing", TurnkeyErrorCodes.INIT_OTP_ERROR);
                 }
-                return initOtpRes.otpId;
+                return {
+                    otpId: initOtpRes.otpId,
+                    otpEncryptionTargetBundle: initOtpRes.otpEncryptionTargetBundle,
+                };
             }, {
                 errorMessage: "Failed to initialize OTP",
                 errorCode: TurnkeyErrorCodes.INIT_OTP_ERROR,
@@ -735,45 +803,38 @@ class TurnkeyClient {
         /**
          * Verifies the OTP code sent to the user.
          *
-         * - This function verifies the OTP code entered by the user against the OTP sent to their contact information (email or phone) using the auth proxy.
-         * - If verification is successful, it returns the sub-organization ID associated with the contact (if it exists) and a verification token.
+         * - Under the hood, the OTP code and an ephemeral client public key are encrypted to the enclave's target key (from `initOtp`) before being sent for verification.
+         * - If verification is successful, it returns a verification token bound to the public key.
          * - The verification token can be used for subsequent login or sign-up flows.
-         * - Handles both email and SMS OTP types.
          *
          * @param params.otpId - ID of the OTP to verify (returned from `initOtp`).
-         * @param params.otpCode - OTP code entered by the user.
-         * @param params.contact - contact information for the user (e.g., email address or phone number).
-         * @param params.otpType - type of OTP being verified (OtpType.Email or OtpType.Sms).
-         * @param params.publicKey - public key the verification token is bound to for ownership verification (client signature verification during login/signup). This public key is optional; if not provided, a new key pair will be generated.
+         * @param params.otpCode - the OTP code entered by the user.
+         * @param params.otpEncryptionTargetBundle - the encryption target bundle returned from `initOtp`.
+         * @param params.publicKey - optional public key to bind to the verification token. If not provided, a new key pair will be generated via the configured `apiKeyStamper`.
          * @returns A promise that resolves to an object containing:
-         *   - subOrganizationId: sub-organization ID if the contact is already associated with a sub-organization, or an empty string if not.
          *   - verificationToken: verification token to be used for login or sign-up.
+         *   - publicKey: the public key bound to the verification token (either the one provided or the auto-generated one).
          * @throws {TurnkeyError} If there is an error during the OTP verification process, such as an invalid code or network failure.
          */
         this.verifyOtp = async (params) => {
-            const { otpId, otpCode, contact, otpType } = params;
-            const resolvedPublicKey = params.publicKey ?? (await this.apiKeyStamper?.createKeyPair());
+            const { otpId, otpCode, otpEncryptionTargetBundle } = params;
+            // we track auto-generated keys so we can clean them up on errors
+            const publicKey = params.publicKey ?? (await this.createApiKeyPair());
+            if (!publicKey) {
+                throw new TurnkeyError("No public key available. Either pass a publicKey or ensure apiKeyStamper is configured.", TurnkeyErrorCodes.INVALID_REQUEST);
+            }
             return withTurnkeyErrorHandling(async () => {
-                const verifyOtpRes = await this.httpClient.proxyVerifyOtp({
+                const encryptedOtpBundle = await encryptOtpCodeToBundle(otpCode, otpEncryptionTargetBundle, publicKey);
+                const verifyOtpRes = await this.httpClient.proxyVerifyOtpV2({
                     otpId: otpId,
-                    otpCode: otpCode,
-                    publicKey: resolvedPublicKey,
+                    encryptedOtpBundle: encryptedOtpBundle,
                 });
                 if (!verifyOtpRes) {
                     throw new TurnkeyError(`OTP verification failed`, TurnkeyErrorCodes.INTERNAL_ERROR);
                 }
-                const accountRes = await this.httpClient.proxyGetAccount({
-                    filterType: OtpTypeToFilterTypeMap[otpType],
-                    filterValue: contact,
-                    verificationToken: verifyOtpRes.verificationToken,
-                });
-                if (!accountRes) {
-                    throw new TurnkeyError(`Account fetch failed`, TurnkeyErrorCodes.ACCOUNT_FETCH_ERROR);
-                }
-                const subOrganizationId = accountRes.organizationId;
                 return {
-                    subOrganizationId: subOrganizationId,
                     verificationToken: verifyOtpRes.verificationToken,
+                    publicKey,
                 };
             }, {
                 errorMessage: "Failed to verify OTP",
@@ -784,19 +845,29 @@ class TurnkeyClient {
                         code: TurnkeyErrorCodes.INVALID_OTP_CODE,
                     },
                 },
+                catchFn: async () => {
+                    // we only clean up the generated key pair if we created it here
+                    if (!params.publicKey) {
+                        try {
+                            await this.deleteApiKeyPair({ publicKey });
+                        }
+                        catch (cleanupError) {
+                            throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
+                        }
+                    }
+                },
             });
         };
         /**
          * Logs in a user using an OTP verification token.
          *
          * - This function logs in a user using the verification token received after OTP verification (from email or SMS).
-         * - If a public key is not provided, a new API key pair will be generated for authentication.
+         * - The client signature is always produced using the private key bound to the verification token during `verifyOtp`.
+         * - The verification token's embedded key becomes the session public key.
          * - Optionally invalidates any existing sessions for the user if `invalidateExisting` is set to true.
          * - Stores the resulting session token under the specified session key, or the default session key if not provided.
-         * - Handles cleanup of unused key pairs if login fails.
          *
          * @param params.verificationToken - verification token received after OTP verification.
-         * @param params.publicKey - public key to use for authentication. If not provided, a new key pair will be generated.
          * @param params.organizationId - optional organization ID to target (defaults to the verified subOrg ID linked to the verification token contact).
          * @param params.invalidateExisting - flag to invalidate existing session for the user.
          * @param params.sessionKey - session key to use for session creation (defaults to the default session key).
@@ -805,34 +876,35 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If there is an error during the OTP login process or if key pair cleanup fails.
          */
         this.loginWithOtp = async (params) => {
-            const { verificationToken, invalidateExisting = false, publicKey = await this.apiKeyStamper?.createKeyPair(), organizationId, sessionKey = SessionKey.DefaultSessionkey, } = params;
+            const { verificationToken, invalidateExisting = false, organizationId, sessionKey = SessionKey.DefaultSessionkey, } = params;
             return withTurnkeyErrorHandling(async () => {
-                const { message, publicKey: clientSignaturePublicKey } = getClientSignatureMessageForLogin({
-                    verificationToken,
-                    sessionPublicKey: publicKey,
+                const { message, publicKey: verificationPublicKey } = getClientSignatureMessageForLogin({ verificationToken });
+                // we sign with the verification token key. This is the key bound during
+                // verifyOtp() and is what Turnkey expects to sign the client signature for login
+                const signature = await this.signWithApiKey({
+                    message,
+                    publicKey: verificationPublicKey,
                 });
-                this.apiKeyStamper?.setTemporaryPublicKey(publicKey);
-                const signature = await this.apiKeyStamper?.sign(message, SignatureFormat.Raw);
                 if (!signature) {
                     throw new TurnkeyError(`Failed to sign client signature for OTP login`, TurnkeyErrorCodes.INTERNAL_ERROR);
                 }
                 const clientSignature = {
                     message: message,
-                    publicKey: clientSignaturePublicKey,
+                    publicKey: verificationPublicKey,
                     scheme: "CLIENT_SIGNATURE_SCHEME_API_P256",
                     signature: signature,
                 };
-                const res = await this.httpClient.proxyOtpLogin({
+                // the verification token's public key is also used as the session public key for login
+                const loginRes = await this.httpClient.proxyOtpLoginV2({
                     verificationToken,
-                    publicKey: publicKey,
-                    invalidateExisting,
+                    publicKey: verificationPublicKey,
                     clientSignature,
+                    invalidateExisting,
                     ...(organizationId && { organizationId }),
                 });
-                if (!res) {
+                if (!loginRes) {
                     throw new TurnkeyError(`Auth proxy OTP login failed`, TurnkeyErrorCodes.OTP_LOGIN_ERROR);
                 }
-                const loginRes = await res;
                 if (!loginRes.session) {
                     throw new TurnkeyError("No session returned from OTP login", TurnkeyErrorCodes.OTP_LOGIN_ERROR);
                 }
@@ -846,21 +918,6 @@ class TurnkeyClient {
             }, {
                 errorMessage: "Failed to log in with OTP",
                 errorCode: TurnkeyErrorCodes.OTP_LOGIN_ERROR,
-                catchFn: async () => {
-                    // Clean up the generated key pair if it wasn't successfully used
-                    if (publicKey) {
-                        try {
-                            await this.apiKeyStamper?.deleteKeyPair(publicKey);
-                        }
-                        catch (cleanupError) {
-                            throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
-                        }
-                    }
-                },
-            }, {
-                finallyFn: async () => {
-                    this.apiKeyStamper?.clearTemporaryPublicKey();
-                },
             });
         };
         /**
@@ -868,7 +925,7 @@ class TurnkeyClient {
          *
          * - This function signs up a user using the verification token received after OTP verification (from email or SMS).
          * - Creates a new sub-organization for the user with the provided parameters and associates the contact (email or phone) with the sub-organization.
-         * - Automatically generates a new API key pair for authentication and session management.
+         * - The verification token's embedded key becomes the session public key.
          * - Stores the resulting session token under the specified session key, or the default session key if not provided.
          * - Handles both email and SMS OTP types, and supports additional sub-organization creation parameters.
          *
@@ -883,7 +940,7 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If there is an error during the OTP sign-up process or session storage.
          */
         this.signUpWithOtp = async (params) => {
-            const { verificationToken, contact, otpType, createSubOrgParams, invalidateExisting, sessionKey, publicKey = await this.apiKeyStamper?.createKeyPair(), } = params;
+            const { verificationToken, contact, otpType, createSubOrgParams, invalidateExisting, sessionKey, } = params;
             // build sign up body without client signature first
             const signUpBody = buildSignUpBody({
                 createSubOrgParams: {
@@ -895,7 +952,7 @@ class TurnkeyClient {
                 },
             });
             return withTurnkeyErrorHandling(async () => {
-                const { message, publicKey: clientSignaturePublicKey } = getClientSignatureMessageForSignup({
+                const { message, publicKey: verificationPublicKey } = getClientSignatureMessageForSignup({
                     verificationToken,
                     ...(signUpBody.userEmail && { email: signUpBody.userEmail }),
                     ...(signUpBody.userPhoneNumber && {
@@ -905,18 +962,22 @@ class TurnkeyClient {
                     authenticators: signUpBody.authenticators,
                     oauthProviders: signUpBody.oauthProviders,
                 });
-                this.apiKeyStamper?.setTemporaryPublicKey(publicKey);
-                const signature = await this.apiKeyStamper?.sign(message, SignatureFormat.Raw);
+                // we sign with the verification token key. This is the key bound during
+                // verifyOtp() and is what Turnkey expects to sign the client signature for signup
+                const signature = await this.signWithApiKey({
+                    message,
+                    publicKey: verificationPublicKey,
+                });
                 if (!signature) {
                     throw new TurnkeyError(`Failed to sign client signature for OTP sign up`, TurnkeyErrorCodes.INTERNAL_ERROR);
                 }
                 const clientSignature = {
                     message: message,
-                    publicKey: clientSignaturePublicKey,
+                    publicKey: verificationPublicKey,
                     scheme: "CLIENT_SIGNATURE_SCHEME_API_P256",
                     signature: signature,
                 };
-                const signupRes = await this.httpClient.proxySignup({
+                const signupRes = await this.httpClient.proxySignupV2({
                     ...signUpBody,
                     clientSignature,
                 });
@@ -925,7 +986,6 @@ class TurnkeyClient {
                 }
                 const otpRes = await this.loginWithOtp({
                     verificationToken,
-                    publicKey: publicKey,
                     ...(invalidateExisting && { invalidateExisting }),
                     ...(sessionKey && { sessionKey }),
                 });
@@ -934,39 +994,26 @@ class TurnkeyClient {
                     appProofs: signupRes.appProofs,
                 };
             }, {
-                catchFn: async () => {
-                    // Clean up the generated key pair if it wasn't successfully used
-                    if (publicKey) {
-                        try {
-                            await this.apiKeyStamper?.deleteKeyPair(publicKey);
-                        }
-                        catch (cleanupError) {
-                            throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
-                        }
-                    }
-                },
                 errorCode: TurnkeyErrorCodes.OTP_SIGNUP_ERROR,
                 errorMessage: "Failed to sign up with OTP",
-            }, {
-                finallyFn: async () => {
-                    this.apiKeyStamper?.clearTemporaryPublicKey();
-                },
             });
         };
         /**
-         * Completes the OTP authentication flow by verifying the OTP code and then either signing up or logging in the user.
+         * Completes the OTP authentication flow by verifying the encrypted OTP bundle and then either signing up or logging in the user.
          *
-         * - This function first verifies the OTP code for the provided contact and OTP type.
+         * - This function encrypts the OTP code and the session public key to the enclave's target key, verifies the OTP, and then either signs up or logs in the user.
          * - If the contact is not associated with an existing sub-organization, it will automatically create a new sub-organization and complete the sign-up flow.
          * - If the contact is already associated with a sub-organization, it will complete the login flow.
-         * - Supports passing a custom public key for authentication, invalidating existing session, specifying a session key, and providing additional sub-organization creation parameters.
+         * - The key bound to the verification token during `verifyOtp` is always reused as the session public key.
+         * - Supports passing a custom public key for binding into the verification token, invalidating existing session, specifying a session key, and providing additional sub-organization creation parameters.
          * - Handles both email and SMS OTP types.
          *
          * @param params.otpId - ID of the OTP to complete (returned from `initOtp`).
-         * @param params.otpCode - OTP code entered by the user.
+         * @param params.otpCode - the OTP code entered by the user.
+         * @param params.otpEncryptionTargetBundle - the encryption target bundle returned from `initOtp`.
          * @param params.contact - contact information for the user (e.g., email address or phone number).
          * @param params.otpType - type of OTP being completed (OtpType.Email or OtpType.Sms).
-         * @param params.publicKey - public key to use for authentication. If not provided, a new key pair may be generated.
+         * @param params.publicKey - public key to bind to the verification token via `verifyOtp`. If not provided, a new key pair will be generated. This key becomes the session public key.
          * @param params.invalidateExisting - flag to invalidate existing sessions for the user.
          * @param params.sessionKey - session key to use for session creation (defaults to the default session key).
          * @param params.createSubOrgParams - parameters for sub-organization creation (e.g., authenticators, user metadata).
@@ -977,18 +1024,30 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If there is an error during OTP verification, sign-up, or login.
          */
         this.completeOtp = async (params) => {
-            const { otpId, otpCode, contact, otpType, publicKey = await this.apiKeyStamper?.createKeyPair(), invalidateExisting = false, sessionKey, createSubOrgParams, } = params;
+            const { otpId, otpCode, otpEncryptionTargetBundle, contact, otpType, invalidateExisting = false, sessionKey, createSubOrgParams, } = params;
+            const publicKey = params.publicKey ?? (await this.createApiKeyPair());
+            if (!publicKey) {
+                throw new TurnkeyError("No public key available. Either pass a publicKey or ensure apiKeyStamper is configured.", TurnkeyErrorCodes.INVALID_REQUEST);
+            }
             return withTurnkeyErrorHandling(async () => {
-                const { subOrganizationId, verificationToken } = await this.verifyOtp({
-                    otpId: otpId,
-                    otpCode: otpCode,
-                    contact: contact,
-                    otpType: otpType,
-                    publicKey: publicKey,
+                const { verificationToken } = await this.verifyOtp({
+                    otpId,
+                    otpCode,
+                    otpEncryptionTargetBundle,
+                    publicKey,
                 });
                 if (!verificationToken) {
                     throw new TurnkeyError("No verification token returned from OTP verification", TurnkeyErrorCodes.VERIFY_OTP_ERROR);
                 }
+                const accountRes = await this.httpClient.proxyGetAccount({
+                    filterType: OtpTypeToFilterTypeMap[otpType],
+                    filterValue: contact,
+                    verificationToken: verificationToken,
+                });
+                if (!accountRes) {
+                    throw new TurnkeyError(`Account fetch failed`, TurnkeyErrorCodes.ACCOUNT_FETCH_ERROR);
+                }
+                const subOrganizationId = accountRes.organizationId;
                 if (!subOrganizationId) {
                     const signUpRes = await this.signUpWithOtp({
                         verificationToken,
@@ -997,7 +1056,6 @@ class TurnkeyClient {
                         ...(createSubOrgParams && { createSubOrgParams }),
                         ...(invalidateExisting && { invalidateExisting }),
                         ...(sessionKey && { sessionKey }),
-                        publicKey: publicKey,
                     });
                     return {
                         ...signUpRes,
@@ -1008,7 +1066,6 @@ class TurnkeyClient {
                 else {
                     const loginRes = await this.loginWithOtp({
                         verificationToken,
-                        publicKey: publicKey,
                         ...(invalidateExisting && { invalidateExisting }),
                         ...(sessionKey && { sessionKey }),
                     });
@@ -1021,6 +1078,16 @@ class TurnkeyClient {
             }, {
                 errorMessage: "Failed to complete OTP process",
                 errorCode: TurnkeyErrorCodes.OTP_COMPLETION_ERROR,
+                catchFn: async () => {
+                    if (!params.publicKey) {
+                        try {
+                            await this.deleteApiKeyPair({ publicKey });
+                        }
+                        catch (cleanupError) {
+                            throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
+                        }
+                    }
+                },
             });
         };
         /**
@@ -1145,7 +1212,7 @@ class TurnkeyClient {
                     // Clean up the generated key pair if it wasn't successfully used
                     if (publicKey) {
                         try {
-                            await this.apiKeyStamper?.deleteKeyPair(publicKey);
+                            await this.deleteApiKeyPair({ publicKey });
                         }
                         catch (cleanupError) {
                             throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
@@ -1182,10 +1249,11 @@ class TurnkeyClient {
                                 providerName,
                                 oidcToken,
                             },
+                            ...(createSubOrgParams?.oauthProviders ?? []),
                         ],
                     },
                 });
-                const signupRes = await this.httpClient.proxySignup(signUpBody);
+                const signupRes = await this.httpClient.proxySignupV2(signUpBody);
                 if (!signupRes) {
                     throw new TurnkeyError(`Auth proxy OAuth signup failed`, TurnkeyErrorCodes.OAUTH_SIGNUP_ERROR);
                 }
@@ -2347,37 +2415,71 @@ class TurnkeyClient {
             });
         };
         /**
-         * Adds an OAuth provider to the user.
+         * Adds one or more OAuth provider audiences to the user.
          *
-         * - This function adds an OAuth provider (e.g., Google, Apple) to the user account.
-         * - If a userId is provided, it adds the provider for that specific user; otherwise, it uses the current session's userId.
-         * - Automatically checks if an account already exists for the provided OIDC token and prevents duplicate associations.
-         * - If the user's email is not set or not verified, attempts to update and verify the email using the email from the OIDC token.
-         * - Handles session management and error reporting for the add provider flow.
+         * - Accepts either an `oidcToken`, a list of `oidcClaims`, or both. At least one must be provided.
+         * - The issuer (`iss`) of the `oidcToken` and all `oidcClaims` must match, ensuring they belong to the same OAuth provider.
+         * - Checks for an existing account for the `oidcToken` (if provided) and for each `oidcClaims` entry, and throws if any of them are already associated with a different sub-organization.
+         * - If the user's email is not set or not verified and an `oidcToken` is provided, attempts to update and verify the email using the email from the token.
+         * - Submits a single `createOauthProviders` request containing the token (if any) and all additional claims.
          * - Optionally allows stamping the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          *
          * @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.oidcToken - OIDC token for the OAuth provider. Either `oidcToken` or `oidcClaims` (or both) must be provided.
+         * @param params.oidcClaims - additional `iss`/`sub`/`aud` claims to register as additional audiences for the same identity.
          * @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.
-         * @throws {TurnkeyError} If there is no active session, if the account already exists, or if there is an error adding the OAuth provider.
+         * @throws {TurnkeyError} If there is no active session, if neither `oidcToken` nor `oidcClaims` was provided, if the issuer claims do not all match, if any of the audiences are already associated with another account, or if there is an error adding the OAuth provider.
          */
         this.addOauthProvider = async (params) => {
-            const { providerName, oidcToken, stampWith = this.config.defaultStamperType, } = params;
+            const { providerName, oidcToken, oidcClaims = [], stampWith = this.config.defaultStamperType, } = params;
+            if (!oidcToken && oidcClaims.length === 0) {
+                throw new TurnkeyError("At least one of `oidcToken` or `oidcClaims` must be provided to add an OAuth provider", TurnkeyErrorCodes.INVALID_REQUEST);
+            }
             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);
-                }
-                if (accountRes.organizationId &&
-                    accountRes.organizationId !== session?.organizationId) {
-                    throw new TurnkeyError("Account already exists with this OIDC token", TurnkeyErrorCodes.ACCOUNT_ALREADY_EXISTS);
+                // Parse the oidc token so we can get the email/iss. The email is used to update the user's email for social linking.
+                // The iss is used to ensure all passed-in claims share the same issuer.
+                const { email: oidcEmail, iss: tokenIss } = oidcToken
+                    ? jwtDecode(oidcToken) || {}
+                    : { email: undefined, iss: undefined };
+                // Verify that all passed-in claims share the same issuer (and match the token's issuer if a token was provided).
+                const issuers = new Set();
+                if (tokenIss)
+                    issuers.add(tokenIss);
+                for (const claim of oidcClaims) {
+                    issuers.add(claim.iss);
+                }
+                if (issuers.size > 1) {
+                    throw new TurnkeyError("All `oidcToken` and `oidcClaims` entries must share the same issuer (`iss`)", TurnkeyErrorCodes.INVALID_REQUEST);
+                }
+                // Check that none of the audiences are already associated with a different sub-organization.
+                const accountChecks = [];
+                if (oidcToken) {
+                    // Look up the sub-organization associated with passed in oidc token
+                    accountChecks.push(this.httpClient.proxyGetAccount({
+                        filterType: FilterType.OidcToken,
+                        filterValue: oidcToken,
+                    }));
+                }
+                // Also look up the sub-organization for each oidcClaim
+                for (const claim of oidcClaims) {
+                    accountChecks.push(this.httpClient.proxyGetAccount({
+                        filterType: FilterType.OidcClaims,
+                        filterValue: JSON.stringify(claim),
+                    }));
+                }
+                const accountResults = await Promise.all(accountChecks);
+                for (const accountRes of accountResults) {
+                    if (!accountRes) {
+                        throw new TurnkeyError(`Account fetch failed`, TurnkeyErrorCodes.ACCOUNT_FETCH_ERROR);
+                    }
+                    if (accountRes.organizationId &&
+                        accountRes.organizationId !== session?.organizationId) {
+                        throw new TurnkeyError("Account already exists with this OIDC token or claims", TurnkeyErrorCodes.ACCOUNT_ALREADY_EXISTS);
+                    }
                 }
                 const userId = params?.userId || session?.userId;
                 if (!userId) {
@@ -2387,9 +2489,7 @@ class TurnkeyClient {
                 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) {
+                if (oidcToken && tokenIss === googleISS) {
                     const verifiedSuborg = await this.httpClient.proxyGetAccount({
                         filterType: "EMAIL",
                         filterValue: oidcEmail,
@@ -2422,14 +2522,13 @@ class TurnkeyClient {
                         }, stampWith);
                     }
                 }
+                const oauthProviders = [
+                    ...(oidcToken ? [{ providerName, oidcToken }] : []),
+                    ...oidcClaims.map((claim) => ({ providerName, oidcClaims: claim })),
+                ];
                 const createProviderRes = await this.httpClient.createOauthProviders({
                     userId,
-                    oauthProviders: [
-                        {
-                            providerName,
-                            oidcToken,
-                        },
-                    ],
+                    oauthProviders,
                 }, stampWith);
                 if (!createProviderRes) {
                     throw new TurnkeyError("Failed to create OAuth provider", TurnkeyErrorCodes.ADD_OAUTH_PROVIDER_ERROR);
@@ -2973,7 +3072,7 @@ class TurnkeyClient {
                 const session = await this.storageManager.getSession(sessionKey);
                 if (session) {
                     await Promise.all([
-                        this.apiKeyStamper?.deleteKeyPair(session.publicKey),
+                        this.deleteApiKeyPair({ publicKey: session.publicKey }),
                         this.storageManager.clearSession(sessionKey),
                     ]);
                 }
@@ -3041,9 +3140,8 @@ class TurnkeyClient {
             if (!this.httpClient) {
                 throw new TurnkeyError("HTTP client is not initialized. Please initialize the client before refreshing the session.", TurnkeyErrorCodes.CLIENT_NOT_INITIALIZED);
             }
-            let keyPair;
+            const keyPair = publicKey ?? (await this.createApiKeyPair());
             return withTurnkeyErrorHandling(async () => {
-                keyPair = publicKey ?? (await this.apiKeyStamper?.createKeyPair());
                 if (!keyPair) {
                     throw new TurnkeyError("Failed to create new key pair.", TurnkeyErrorCodes.INTERNAL_ERROR);
                 }
@@ -3063,6 +3161,17 @@ class TurnkeyClient {
             }, {
                 errorMessage: "Failed to refresh session",
                 errorCode: TurnkeyErrorCodes.REFRESH_SESSION_ERROR,
+                catchFn: async () => {
+                    // we only delete the keypair if we generated it here
+                    if (!publicKey) {
+                        try {
+                            await this.deleteApiKeyPair({ publicKey: keyPair });
+                        }
+                        catch (cleanupError) {
+                            throw new TurnkeyError("Failed to clean up generated key pair", TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
+                        }
+                    }
+                },
             });
         };
         /**
@@ -3183,7 +3292,7 @@ class TurnkeyClient {
                 for (const publicKey of publicKeys) {
                     if (!sessionTokensMap[publicKey]) {
                         try {
-                            await this.apiKeyStamper?.deleteKeyPair(publicKey);
+                            await this.deleteApiKeyPair({ publicKey });
                         }
                         catch (error) {
                             throw new TurnkeyError(`Failed to delete unused key pair ${publicKey}`, TurnkeyErrorCodes.INTERNAL_ERROR, error);
@@ -3198,34 +3307,84 @@ class TurnkeyClient {
         /**
          * Creates a new API key pair and returns the public key.
          *
-         * - This function generates a new API key pair and stores it in the underlying key store (IndexedDB).
+         * - This function generates a new API key pair and stores it in the underlying key store.
          * - If an external key pair is provided, it will use that key pair for creation instead of generating a new one.
-         * - If `storeOverride` is set to true, the generated or provided public key will be set as the override key in the API key stamper, making it the active key for subsequent signing operations.
          * - Ensures the API key stamper is initialized before proceeding.
          * - Handles both native CryptoKeyPair objects and raw key material.
          *
          * @param params.externalKeyPair - An externally generated key pair (either a CryptoKeyPair or an object with publicKey/privateKey strings) to use instead of generating a new one.
-         * @param params.storeOverride - If true, sets the generated or provided public key as the override key in the API key stamper (defaults to false).
          * @return A promise that resolves to the public key of the created or provided API key pair as a string.
          * @throws {TurnkeyError} If the API key stamper is not initialized or if there is an error during key pair creation or storage.
          */
         this.createApiKeyPair = async (params) => {
             return withTurnkeyErrorHandling(async () => {
                 const externalKeyPair = params?.externalKeyPair;
-                const storeOverride = params?.storeOverride ?? false;
                 if (!this.apiKeyStamper) {
                     throw new TurnkeyError("API Key Stamper is not initialized.", TurnkeyErrorCodes.INTERNAL_ERROR);
                 }
                 const publicKey = await this.apiKeyStamper.createKeyPair(externalKeyPair ? externalKeyPair : undefined);
-                if (storeOverride && publicKey) {
-                    this.apiKeyStamper.setTemporaryPublicKey(publicKey);
-                }
                 return publicKey;
             }, {
                 errorMessage: "Failed to create API key pair",
                 errorCode: TurnkeyErrorCodes.CREATE_API_KEY_PAIR_ERROR,
             });
         };
+        /**
+         * Deletes an API key pair from persistent storage.
+         *
+         * - This function removes a stored API key pair from the underlying key store (IndexedDB) based on its public key.
+         * - Ensures that the API key stamper is initialized before proceeding with deletion.
+         * - Intended for cleaning up key pairs that are not associated with active sessions, such as after failed authentication attempts where a temporary key pair was created but never used.
+         * - Should NOT be used to delete key pairs that are associated with active sessions; use `clearSession` or `clearAllSessions` instead.
+         *
+         * @param params.publicKey - The public key of the API key pair to delete.
+         * @returns A promise that resolves when the key pair is successfully deleted.
+         * @throws {TurnkeyError} If the API key stamper is not initialized or if there is an error during key pair deletion.
+         */
+        this.deleteApiKeyPair = async (params) => {
+            const { publicKey } = params;
+            return withTurnkeyErrorHandling(async () => {
+                if (!this.apiKeyStamper) {
+                    throw new TurnkeyError("API Key Stamper is not initialized.", TurnkeyErrorCodes.INTERNAL_ERROR);
+                }
+                await this.apiKeyStamper.deleteKeyPair(publicKey);
+            }, {
+                errorMessage: "Failed to delete API key pair",
+                errorCode: TurnkeyErrorCodes.DELETE_API_KEY_PAIR_ERROR,
+            });
+        };
+        /**
+         * Signs a message using a key pair stored in the API key stamper.
+         *
+         * - This function signs the provided message string with the private key identified by `publicKey`.
+         * - The message is SHA-256 hashed internally before signing (ECDSA P-256).
+         * - Returns a compact hex signature (r || s) suitable for use as a client signature.
+         * - The key pair must already exist in the key store (e.g., created via `createApiKeyPair`).
+         *
+         * @param params.message - the message string to sign.
+         * @param params.publicKey - the public key identifying which key pair to sign with.
+         * @returns A promise that resolves to the compact hex signature string.
+         * @throws {TurnkeyError} If the API key stamper is not initialized or the key pair is not found.
+         */
+        this.signWithApiKey = async (params) => {
+            const { message, publicKey } = params;
+            let previousTemporaryKey;
+            return withTurnkeyErrorHandling(async () => {
+                if (!this.apiKeyStamper) {
+                    throw new TurnkeyError("API Key Stamper is not initialized.", TurnkeyErrorCodes.INTERNAL_ERROR);
+                }
+                previousTemporaryKey = this.apiKeyStamper.getTemporaryPublicKey();
+                this.apiKeyStamper.setTemporaryPublicKey(publicKey);
+                return await this.apiKeyStamper.sign(message, SignatureFormat.Raw);
+            }, {
+                errorMessage: "Failed to sign with API key",
+                errorCode: TurnkeyErrorCodes.INTERNAL_ERROR,
+            }, {
+                finallyFn: async () => {
+                    this.apiKeyStamper?.setTemporaryPublicKey(previousTemporaryKey);
+                },
+            });
+        };
         /**
          * Fetches the WalletKit proxy authentication configuration from the auth proxy.
          *
@@ -3398,7 +3557,7 @@ class TurnkeyClient {
      * @param params.stampWith - Optional stamper to use for polling.
      *
      * @returns A promise resolving to the transaction status payload if successful.
-     * @throws {Error | string} If the transaction fails or is cancelled.
+     * @throws {TurnkeyError} If the transaction fails, is cancelled, or times out.
      */
     async pollTransactionStatus(params) {
         const { organizationId: organizationIdFromParams, stampWith = this.config.defaultStamperType, sendTransactionStatusId, pollingIntervalMs, } = params;
@@ -3417,14 +3576,13 @@ class TurnkeyClient {
                         sendTransactionStatusId,
                     });
                     const txStatus = resp?.txStatus;
-                    const txError = resp?.txError;
                     if (!txStatus)
                         return;
-                    if (txError || txStatus === "FAILED" || txStatus === "CANCELLED") {
+                    if (txStatus === "FAILED" || txStatus === "CANCELLED") {
                         // TODO: use API enum in the future
                         clearInterval(ref);
                         clearTimeout(timeoutRef);
-                        reject(txError || `Transaction ${txStatus}`);
+                        reject(new TurnkeyError(resp.error?.message || `Transaction ${resp.txStatus}`, TurnkeyErrorCodes.POLL_TRANSACTION_STATUS_ERROR, resp));
                         return;
                     }
                     if (txStatus === "COMPLETED" || txStatus === "INCLUDED") {