Migrate to encrypted OTP flows

Turnkey’s current email and SMS OTP flows encrypt each OTP attempt before it leaves the client. The client encrypts the code and a session public key to a Turnkey enclave target key. After successful verification, the resulting verification token is bound to the client public key, so an application server cannot read the OTP or use the token to authenticate without the matching client private key. This guide is for integrations that use legacy OTP activities or SDK methods that send otpCode in plaintext. New integrations should use the current flow documented in Email auth & recovery and SMS authentication.

Migrate each OTP attempt as a unit. Do not start an attempt with a legacy INIT_OTP activity and finish it with the updated VERIFY_OTP_V2 or OTP_LOGIN_V2 activities. The encryption bundle, verification token, and client key belong to the same attempt and are not interchangeable with the legacy flow.

What changed

Stage	Legacy SDK activity	Current SDK activity	Required change
Initiate	`ACTIVITY_TYPE_INIT_OTP` or `ACTIVITY_TYPE_INIT_OTP_V2`	`ACTIVITY_TYPE_INIT_OTP_V3`	Keep the returned `otpEncryptionTargetBundle` with the `otpId` until verification.
Verify	`ACTIVITY_TYPE_VERIFY_OTP`	`ACTIVITY_TYPE_VERIFY_OTP_V2`	Replace plaintext `otpCode` and `publicKey` with an `encryptedOtpBundle`.
Log in	`ACTIVITY_TYPE_OTP_LOGIN`	`ACTIVITY_TYPE_OTP_LOGIN_V2`	Include a `clientSignature` made by the key bound during verification.
Sign up	`ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V7`	`ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V8`	Include a `clientSignature` when the verification token is bound to a public key. Version 8 and later do not accept legacy OTP verification tokens.

ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V7 is transitional: it accepts both legacy verification tokens and the enclave-issued tokens returned by VERIFY_OTP_V2. ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V8 accepts only enclave-issued tokens. During a staged rollout, legacy attempts must remain on V7; updated attempts can use V7 or V8.

The updated verification flow is:

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

See OTP login flow for the protocol diagram and security properties.

Upgrade the SDKs

The encrypted flow was introduced in the following releases. Use these versions or later, and upgrade related Turnkey packages together so their generated activity types and request shapes remain compatible.

Package	Minimum version
`@turnkey/sdk-react`	`6.0.0`
`@turnkey/sdk-browser`	`6.0.0`
`@turnkey/sdk-server`	`6.0.0`
`@turnkey/react-wallet-kit`	`2.0.0`
`@turnkey/react-native-wallet-kit`	`2.0.0`
`@turnkey/core`	`2.0.0`
`@turnkey/http`	`4.0.0`
`@turnkey/sdk-types`	`1.0.0`
`@turnkey/crypto`	`2.9.0`

Choose the section below that matches your integration.

Wallet Kit and Core
Legacy React SDK
Server and low-level clients

In @turnkey/react-wallet-kit, @turnkey/react-native-wallet-kit, and @turnkey/core, initOtp now returns an object instead of a plain OTP ID. Keep both values:

// 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",
});

Pass the bundle to verifyOtp. The SDK encrypts the OTP code and public key before calling Turnkey:

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

verifyOtp no longer accepts contact or otpType, and it no longer returns subOrganizationId. Use completeOtp to perform verification plus account lookup and login/signup, or call proxyGetAccount separately after verification.loginWithOtp and signUpWithOtp no longer accept a separate publicKey. They reuse the key bound during verifyOtp and generate the required client signature automatically.

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

@turnkey/sdk-react is the legacy React SDK. For new projects, use @turnkey/react-wallet-kit; see Migrating from @turnkey/sdk-react.If you are maintaining an @turnkey/sdk-react integration, the OtpVerification component now requires the encryption target bundle returned by sendOtp:

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}
/>

The component handles creation of the encrypted OTP bundle. Make sure a resend replaces both otpId and otpEncryptionTargetBundle; never combine values from separate attempts.

sendOtp and initOtp now return an encryption target bundle. Persist it only for the lifetime of the OTP attempt and return it to the client that will verify the code.

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

Replace the plaintext otpCode field with a bundle created on the client:

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

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

const { verificationToken } = await server.verifyOtp({
  otpId,
  encryptedOtpBundle,
  sessionLengthSeconds,
});

The private key matching publicKey must stay on the client. Use it to sign the login or signup message, then send the resulting clientSignature to the backend:

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

The otp-auth/with-backend example shows the full split between client-side encryption and signing and server-side Turnkey API calls.

Update policies before deploying

If a policy checks exact activity versions, update it before the new SDKs begin submitting activities. At minimum, review policies that name:

ACTIVITY_TYPE_INIT_OTP or ACTIVITY_TYPE_INIT_OTP_V2
ACTIVITY_TYPE_VERIFY_OTP
ACTIVITY_TYPE_OTP_LOGIN
ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V7

During a staged rollout, exact-type policies must allow both legacy and updated versions until all clients and servers use the new flow. This does not make the activity versions interchangeable within an OTP attempt. Prefer activity.kind when the same policy should cover every version of a specific activity:

{
  "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']"
}

CREATE_SUB_ORGANIZATION covers every version of sub-organization creation, not only OTP signup. Preserve any existing restrictions on who may create a sub-organization and which parameters they may submit.

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.
After all clients have migrated, remove legacy activity versions from exact-version policies.

For the complete set of SDK breaking changes shipped with this migration, see tkhq/sdk#1250.

Get started

Features

Reference

Migrate to encrypted OTP flows

What changed

Upgrade the SDKs

Update policies before deploying

Rollout checklist

​What changed

​Upgrade the SDKs

​Update policies before deploying

​Rollout checklist

What changed

Upgrade the SDKs

Update policies before deploying

Rollout checklist