> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turnkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to encrypted OTP flows

> How to migrate to Turnkey's new security-upgraded OTP authentication 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](/features/authentication/email) and [SMS authentication](/features/authentication/sms).

<Warning>
  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.
</Warning>

## 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. |

<Note>
  `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.
</Note>

The updated verification flow is:

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.

See [OTP login flow](/security/enclave-secure-channels#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`](https://github.com/tkhq/sdk/blob/main/packages/sdk-react/CHANGELOG.md#600)               |
| `@turnkey/sdk-browser`             | [`6.0.0`](https://github.com/tkhq/sdk/blob/main/packages/sdk-browser/CHANGELOG.md#600)             |
| `@turnkey/sdk-server`              | [`6.0.0`](https://github.com/tkhq/sdk/blob/main/packages/sdk-server/CHANGELOG.md#600)              |
| `@turnkey/react-wallet-kit`        | [`2.0.0`](https://github.com/tkhq/sdk/blob/main/packages/react-wallet-kit/CHANGELOG.md#200)        |
| `@turnkey/react-native-wallet-kit` | [`2.0.0`](https://github.com/tkhq/sdk/blob/main/packages/react-native-wallet-kit/CHANGELOG.md#200) |
| `@turnkey/core`                    | [`2.0.0`](https://github.com/tkhq/sdk/blob/main/packages/core/CHANGELOG.md#200)                    |
| `@turnkey/http`                    | [`4.0.0`](https://github.com/tkhq/sdk/blob/main/packages/http/CHANGELOG.md#400)                    |
| `@turnkey/sdk-types`               | [`1.0.0`](https://github.com/tkhq/sdk/blob/main/packages/sdk-types/CHANGELOG.md#100)               |
| `@turnkey/crypto`                  | [`2.9.0`](https://github.com/tkhq/sdk/blob/main/packages/crypto/CHANGELOG.md#290)                  |

Choose the section below that matches your integration.

<Tabs>
  <Tab title="Wallet Kit and Core">
    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:

    ```ts theme={"system"}
    // 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:

    ```ts theme={"system"}
    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.

    ```ts theme={"system"}
    await loginWithOtp({
      verificationToken,
      invalidateExisting: true,
    });
    ```
  </Tab>

  <Tab title="Legacy React SDK">
    `@turnkey/sdk-react` is the legacy React SDK. For new projects, use `@turnkey/react-wallet-kit`; see [Migrating from `@turnkey/sdk-react`](/solutions/embedded-wallets/integration-guide/react/migrating-sdk-react).

    If you are maintaining an `@turnkey/sdk-react` integration, the `OtpVerification` component now requires the encryption target bundle returned by `sendOtp`:

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

    ```tsx theme={"system"}
    <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.
  </Tab>

  <Tab title="Server and low-level clients">
    `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.

    ```ts theme={"system"}
    const { otpId, otpEncryptionTargetBundle } = await server.sendOtp({
      // ...
    });
    ```

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

    ```ts theme={"system"}
    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:

    ```ts theme={"system"}
    await server.otpLogin({
      suborgID,
      verificationToken,
      publicKey,
      clientSignature,
      sessionLengthSeconds,
    });
    ```

    The [`otp-auth/with-backend`](https://github.com/tkhq/sdk/tree/main/examples/authentication/otp-auth/with-backend) example shows the full split between client-side encryption and signing and server-side Turnkey API calls.
  </Tab>
</Tabs>

## 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:

```json theme={"system"}
{
  "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']"
}
```

<Note>
  `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.
</Note>

## 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](https://github.com/tkhq/sdk/pull/1250).