Migrate to encrypted OTP flows

​

What changed

1. INIT_OTP_V3 returns otpId and otpEncryptionTargetBundle.
2. The client generates or selects a P-256 key pair.
3. The client uses encryptOtpCodeToBundle to encrypt the OTP code and public key with otpEncryptionTargetBundle.
4. VERIFY_OTP_V2 accepts the encrypted bundle and returns a verification token bound to the client public key.
5. The client signs the login or signup payload with the same private key.
6. OTP_LOGIN_V2 or the sub-organization creation flow validates the verification token and client signature.

​

Migrating from legacy OTP Auth

​

Replace initialization, verification, and login

1. Before you deploy: update policies. In the parent organization, permit the three replacement activities for the non-root API user that submits them, preserving existing user and organization restrictions. A root API user satisfying a root quorum threshold of one does not need these additional allow policies. See Update policies before deploying.
2. Backend: replace initOtpAuth with initOtp. Submit ACTIVITY_TYPE_INIT_OTP_V3 under the parent organization with the contact, otpType (OTP_TYPE_EMAIL or OTP_TYPE_SMS), and required appName. Return otpId and otpEncryptionTargetBundle to the client.
   • If you use INIT_OTP_AUTH or INIT_OTP_AUTH_V2, move appName out of emailCustomization into the top-level appName field. INIT_OTP_V3 requires it, and its emailCustomization no longer accepts appName. See Breaking change: appName required.
   • If you rely on the organization’s default email template, have Turnkey configure it for ACTIVITY_TYPE_INIT_OTP. Default templates registered for ACTIVITY_TYPE_INIT_OTP_AUTH are not selected automatically by the new flow. An existing template passed explicitly through emailCustomization.templateId can still be selected. Review its content for compatibility with the new flow.
   • Review your other email and SMS customization parameters against the new activity rather than copying the legacy request unchanged.
3. Client: encrypt the code. Generate or select a P-256 key pair. Use encryptOtpCodeToBundle(otpCode, otpEncryptionTargetBundle, publicKey) to encrypt the code and public key, and send only the resulting encryptedOtpBundle to your backend. The private key stays on the client.
4. Backend: verify with verifyOtp. Submit ACTIVITY_TYPE_VERIFY_OTP_V2 with otpId and encryptedOtpBundle, using the same organization ID as initialization. Return the verificationToken to the client; it is bound to the client key used in the encrypted bundle.
5. Backend: resolve the user’s sub-organization. After verification, look up the sub-organization for the contact, for example with getSubOrgIds filtered by EMAIL or PHONE_NUMBER. In the legacy flow you resolved the sub-organization before initialization, because INIT_OTP_AUTH is submitted to it. Move that lookup here, after the code is verified.
6. Client: sign the login message. Build the message with getClientSignatureMessageForLogin and sign it with the private key bound during verification. The message covers the token ID and the session public key; do not sign an arbitrary JSON representation of the token.
7. Backend: replace otpAuth with otpLogin. Submit ACTIVITY_TYPE_OTP_LOGIN_V2 to the user’s sub-organization with verificationToken, the session publicKey, and clientSignature.
8. Client: store and use the session. Use the returned session with the private key matching the session publicKey you passed to OTP_LOGIN_V2, following your SDK’s session handling. Remove the legacy credential-bundle decryption and import step. See Credential handling changes.

// Backend: INIT_OTP_AUTH is submitted to the user's sub-organization,
// so the sub-organization must be resolved first.
const { otpId } = await turnkey.apiClient().initOtpAuth({
  organizationId: subOrgId,
  otpType: "OTP_TYPE_EMAIL",
  contact: email,
  appName: "Example App",
});

// Backend: the client sends the plaintext code and a target public key.
const { credentialBundle } = await turnkey.apiClient().otpAuth({
  organizationId: subOrgId,
  otpId,
  otpCode,
  targetPublicKey,
});

// Client: decrypt credentialBundle and import the API key.

const { otpId, otpEncryptionTargetBundle } = await turnkey.apiClient().initOtp({
  otpType: "OTP_TYPE_EMAIL",
  contact: email,
  appName: "Example App",
});

import { encryptOtpCodeToBundle } from "@turnkey/crypto";
import {
  getClientSignatureMessageForLogin,
  useTurnkey,
} from "@turnkey/react-wallet-kit";

// Inside your React component or custom hook:
const { createApiKeyPair, signWithApiKey, storeSession } = useTurnkey();

// Create a fresh key for this attempt and retain publicKey in component state.
// Wallet Kit stores the private key on the client.
const publicKey = await createApiKeyPair();
const encryptedOtpBundle = await encryptOtpCodeToBundle(
  otpCode,
  otpEncryptionTargetBundle,
  publicKey,
);

// Use the same parent organization as initialization.
const { verificationToken } = await turnkey.apiClient().verifyOtp({
  otpId,
  encryptedOtpBundle,
});

const { organizationIds } = await turnkey.apiClient().getSubOrgIds({
  filterType: "EMAIL",
  filterValue: email,
});
const subOrgId = organizationIds[0]; // If none is found, sign up instead.

const { message } = getClientSignatureMessageForLogin({ verificationToken });
const signature = await signWithApiKey({ message, publicKey });
const clientSignature = {
  scheme: "CLIENT_SIGNATURE_SCHEME_API_P256" as const,
  publicKey,
  message,
  signature,
};

const { session } = await turnkey.apiClient().otpLogin({
  organizationId: subOrgId,
  verificationToken,
  publicKey,
  clientSignature,
});

await storeSession({ sessionToken: session });

​

Credential handling changes

​

Migrating from legacy email authentication and recovery

• ACTIVITY_TYPE_EMAIL_AUTH, ACTIVITY_TYPE_EMAIL_AUTH_V2, or ACTIVITY_TYPE_EMAIL_AUTH_V3
• ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY or ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY_V2, followed by ACTIVITY_TYPE_RECOVER_USER

​

Choose the flow that matches your integration

​

Before you deploy

• Upgrade the relevant SDK packages to the versions listed in Upgrade the SDKs.
• Confirm that FEATURE_NAME_OTP_EMAIL_AUTH is enabled for the target sub-organization, as it is by default for new sub-organizations. The legacy email-authentication and email-recovery feature settings do not substitute for this setting. If it is disabled, enabling it requires the sub-organization’s own root quorum; the parent organization cannot enable it on the user’s behalf during recovery. See Organization features.
• Update activity permissions to allow ACTIVITY_TYPE_INIT_OTP_V3, ACTIVITY_TYPE_VERIFY_OTP_V2, and ACTIVITY_TYPE_OTP_LOGIN_V2 for the users submitting those requests. For recovery, also ensure the recovering user can submit ACTIVITY_TYPE_CREATE_AUTHENTICATORS_V2 with the recovery session. Preserve existing user, organization, and operation restrictions; see Update policies before deploying.
• Review credential-type checks in policy consensus expressions. Legacy checks for CREDENTIAL_TYPE_EMAIL_AUTH_KEY_P256 or CREDENTIAL_TYPE_RECOVER_USER_KEY_P256 do not match requests stamped with the new CREDENTIAL_TYPE_LOGIN sessions. When updating these checks, retain the recovery flow’s restrictions on permitted operations and users; matching a login session alone does not restrict it to recovery.
• Review your email templates and callback UI. The replacement sends an OTP to verify, rather than a recovery or authentication credential bundle to import.
• Review existing MFA policy conditions as well as which user stamps each request. Conditions that name legacy activity kinds or versions must be updated for the replacement flow.

​

Preserve existing MFA enforcement

​

Replace email authentication

1. Initialize email OTP. Replace emailAuth with initOtp, submitting ACTIVITY_TYPE_INIT_OTP_V3 under the parent organization. Set otpType to OTP_TYPE_EMAIL, provide the user’s email as contact, and include the required top-level appName. Return both otpId and otpEncryptionTargetBundle to the client.
2. Encrypt the OTP on the client. Generate or select a client P-256 key pair. Use encryptOtpCodeToBundle to encrypt the OTP and public key with the returned target bundle. Keep the private key and plaintext OTP on the client.
3. Verify the encrypted submission. Submit ACTIVITY_TYPE_VERIFY_OTP_V2 with otpId and encryptedOtpBundle, using the same organization ID as initialization. Retain the returned verificationToken with the client key used for this attempt.
4. Resolve the existing account and complete login. Identify the user’s sub-organization after verification. Submit ACTIVITY_TYPE_OTP_LOGIN_V2 to that sub-organization with the verification token, session public key, and required client signature, using the request stamp chosen in Preserve existing MFA enforcement.
5. Use the returned session. Store the session using your SDK’s session handling. Remove the legacy credential-bundle decryption and import step. The signing private key remains on the client.

​

Replace email recovery

{
  "sessionProfileName": "recovery-authenticator-only",
  "scope": "activity.kind == 'CREATE_AUTHENTICATORS'",
  "expirationSeconds": "600"
}

1. Resolve the existing account and obtain a recovery session. Submit ACTIVITY_TYPE_OTP_LOGIN_V2 to the user’s sub-organization with the verification token, session public key, required client signature, and recovery sessionProfileId. Use the request stamp chosen in Preserve existing MFA enforcement and complete any MFA challenges. This login creates the recovery session. Omitting sessionProfileId creates a default read/write session with no scope restrictions.
2. Enroll a replacement passkey. Complete WebAuthn registration on the client, then submit ACTIVITY_TYPE_CREATE_AUTHENTICATORS_V2 for the recovering user, stamped with the recovery session. This replaces the legacy recoverUser step.
3. Sign in with the new passkey. Confirm that the new authenticator works before considering recovery complete. Handle removal of lost or compromised authenticators according to your application’s recovery policy.

await legacyRecoveryClient.recoverUser({
  organizationId: subOrgId,
  userId,
  authenticator,
});

await recoverySessionClient.createAuthenticators({
  organizationId: subOrgId,
  userId,
  authenticators: [authenticator],
});

​

Review session invalidation and legacy credentials

​

Verify the migration

• An existing user can complete email authentication or recovery.
• Recovery enrolls a working replacement authenticator in the existing account.
• MFA conditions cover the replacement activities and still trigger the intended challenges. During rollout, verify the legacy flow remains covered too.
• Any recovery-session restrictions prevent operations outside the intended scope.
• If email alone should grant only recovery access, MFA requires an additional factor for normal login and sensitive direct attested requests, including for root users with a quorum threshold of one. Test omitted or changed sessionProfileId values; ordinary authorization policies and a recovery session profile do not enforce this restriction for those users.
• The replacement passkey is subject to the intended authorization and MFA policies when used for normal login and subsequent operations.
• Session expiration and invalidation behave as expected, including the effect on sessions created through other login methods.
• Subsequent wallet operations work with the normal login session; recovery sessions remain limited to authenticator enrollment.
• Legacy method calls and credential-bundle handling have been removed.

​

Upgrade the SDKs

​

Wallet Kit and Core login activities

// Before
const otpId = await initOtp({
  otpType: OtpType.Email,
  contact: "user@example.com",
});

// After
const { otpId, otpEncryptionTargetBundle } = await initOtp({
  otpType: OtpType.Email,
  contact: "user@example.com",
});

const { verificationToken } = await verifyOtp({
  otpId,
  otpCode,
  otpEncryptionTargetBundle,
});

await loginWithOtp({
  verificationToken,
  invalidateExisting: true,
});

const { otpId, otpEncryptionTargetBundle } = await server.sendOtp({
  appName: "Example App",
  otpType: OtpType.Sms,
  contact: phoneInput,
  customSmsMessage: "Your OTP is {{.OtpCode}}",
  userIdentifier: publicKey,
});

<OtpVerification
  type={type}
  contact={contact}
  otpId={otpId}
  otpEncryptionTargetBundle={otpEncryptionTargetBundle}
  onValidateSuccess={handleValidateSuccess}
  onResendCode={handleResendCode}
/>

const { otpId, otpEncryptionTargetBundle } = await server.sendOtp({
  // ...
});

import { encryptOtpCodeToBundle } from "@turnkey/crypto";

const encryptedOtpBundle = await encryptOtpCodeToBundle(
  otpCode,
  otpEncryptionTargetBundle,
  publicKey,
);

const { verificationToken } = await server.verifyOtp({
  otpId,
  encryptedOtpBundle,
  sessionLengthSeconds, // Verification token lifetime, not session length.
});

await server.otpLogin({
  suborgID,
  verificationToken,
  publicKey,
  clientSignature,
  sessionLengthSeconds,
});

​

Update policies before deploying

• ACTIVITY_TYPE_INIT_OTP or ACTIVITY_TYPE_INIT_OTP_V2
• ACTIVITY_TYPE_VERIFY_OTP
• ACTIVITY_TYPE_OTP_LOGIN
• ACTIVITY_TYPE_INIT_OTP_AUTH, ACTIVITY_TYPE_INIT_OTP_AUTH_V2, or ACTIVITY_TYPE_INIT_OTP_AUTH_V3
• ACTIVITY_TYPE_OTP_AUTH
• ACTIVITY_TYPE_EMAIL_AUTH, ACTIVITY_TYPE_EMAIL_AUTH_V2, or ACTIVITY_TYPE_EMAIL_AUTH_V3
• ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY, ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY_V2, or ACTIVITY_TYPE_RECOVER_USER
• ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V7

​

Policies for legacy OTP Auth

{
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<YOUR_API_USER_ID>')",
  "condition": "activity.kind in ['INIT_OTP_AUTH', 'OTP_AUTH', 'INIT_OTP', 'VERIFY_OTP', 'OTP_LOGIN']"
}

{
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<YOUR_API_USER_ID>')",
  "condition": "activity.type in ['ACTIVITY_TYPE_INIT_OTP_V3', 'ACTIVITY_TYPE_VERIFY_OTP_V2', 'ACTIVITY_TYPE_OTP_LOGIN_V2']"
}

​

Policies for other OTP flows

{
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<YOUR_API_USER_ID>')",
  "condition": "activity.kind in ['INIT_OTP', 'VERIFY_OTP', 'OTP_LOGIN', 'CREATE_SUB_ORGANIZATION']"
}

​

Rollout checklist

• Update policies before deploying updated SDKs.
• Upgrade the frontend and backend Turnkey packages together.
• Store otpId, otpEncryptionTargetBundle, and the client key as state for one OTP attempt.
• On resend, replace all attempt state rather than reusing an old bundle or key.
• Test email and SMS separately if your application supports both.
• Test both an existing-user login and a new-user signup.
• Confirm that OTP codes are sent to your backend only as encryptedOtpBundle.
• For legacy OTP Auth integrations, confirm there are no remaining initOtpAuth or otpAuth callers, and that clients use sessions instead of decrypting credentialBundle responses.
• Test session expiration, invalidation, and a wallet operation with the new session. Account for any legacy OTP Auth credentials that have not yet expired or been revoked.
• After all clients have migrated, remove legacy activity versions from exact-version policies, and replace kind-based OTP policies with exact types so the plaintext flows are no longer permitted.