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

# Migrating from v1 to v2

> How Core API v1 requests are handled going forward and how to migrate to v2

## What's Happening

**Core API v1 endpoints will be shut down on July 31, 2026.** After that date, all v1 requests will be rejected and v1 wallets that have not been migrated will be inaccessible. There is no automatic routing — v1 and v2 are distinct paths and you must update your integration explicitly.

We recommend migrating before the deadline. The v2 API is more secure, removes the need to manage `encryption_context` and `recovery_key`, and ties wallet access directly to your users' JWT identities.

## What Changed

|                      | v1                                  | v2                                 |
| -------------------- | ----------------------------------- | ---------------------------------- |
| Wallet creation      | `encryption_context` (user secret)  | `auth_jwt` (user's IdP JWT)        |
| Signing / operations | `encryption_context` + `access_key` | `op_jwt` + `access_key`            |
| Recovery             | `recovery_key` stored in your DB    | Handled by your identity provider  |
| Wallet binding       | Passphrase-derived secret           | Cryptographic JWT identity binding |

## Migration Steps

<Steps>
  <Step title="Update wallet creation">
    Replace `encryption_context` with `auth_jwt` — the user's JWT from your identity provider.

    **v1:**

    ```bash cURL icon="square-terminal" theme={null}
    curl -X POST 'https://tee.magiclabs.com/v1/api/wallet' \
      -H 'Content-Type: application/json' \
      -H 'x-magic-secret-key: sk_live_XXXXXXXX' \
      -d '{
        "encryption_context": "hashed_passcode",
        "network": "eth_mainnet",
        "wallet_group_id": "58a08494-3c83-439a-8a07-551f20xxxxxx"
      }'
    ```

    **v2:**

    ```bash cURL icon="square-terminal" theme={null}
    curl -X POST 'https://tee.magiclabs.com/v2/api/wallet' \
      -H 'Content-Type: application/json' \
      -H 'x-magic-secret-key: sk_live_XXXXXXXX' \
      -d '{
        "auth_jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGgueW91cmFwcC5jb20iLCJzdWIiOiJ1c2VyXzEyMzQ1NiIsImF1ZCI6Imh0dHBzOi8vdGVlLm1hZ2ljbGFicy5jb20iLCJpYXQiOjE3NTE2NzIwMDAsImV4cCI6MTc1MTY3MjMwMH0.SIGNATURE",
        "network": "eth_mainnet",
        "wallet_group_id": "58a08494-3c83-439a-8a07-551f20xxxxxx"
      }'
    ```

    <Warning>
      v2 wallet creation no longer returns a `recovery_key`. You only need to store `wallet_id` and `access_key`.
    </Warning>
  </Step>

  <Step title="Update signing operations">
    Replace `encryption_context` with `op_jwt`. The `access_key` and `wallet_id` remain the same.

    **v1:**

    ```bash cURL icon="square-terminal" theme={null}
    curl -X POST 'https://tee.magiclabs.com/v1/api/wallet/sign_data' \
      -H 'Content-Type: application/json' \
      -H 'x-magic-secret-key: sk_live_XXXXXXXX' \
      -d '{
        "encryption_context": "hashed_passcode",
        "raw_data_hash": "0xabc...",
        "access_key": "access_key",
        "wallet_id": "e982b4a3-14d3-4d66-a3ac-fadfc3xxxxxx"
      }'
    ```

    **v2:**

    ```bash cURL icon="square-terminal" theme={null}
    curl -X POST 'https://tee.magiclabs.com/v2/api/wallet/sign_data' \
      -H 'Content-Type: application/json' \
      -H 'x-magic-secret-key: sk_live_XXXXXXXX' \
      -d '{
        "op_jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGgueW91cmFwcC5jb20iLCJzdWIiOiJ1c2VyXzEyMzQ1NiIsImF1ZCI6Imh0dHBzOi8vdGVlLm1hZ2ljbGFicy5jb20iLCJpYXQiOjE3NTE2NzIwMDAsImV4cCI6MTc1MTY3MjMwMH0.SIGNATURE",
        "raw_data_hash": "0xabc...",
        "access_key": "access_key",
        "wallet_id": "e982b4a3-14d3-4d66-a3ac-fadfc3xxxxxx"
      }'
    ```

    The same pattern applies to `sign_message` and `sign_transaction` — swap `encryption_context` for `op_jwt` and update the path from `/v1/` to `/v2/`.
  </Step>

  <Step title="Issue op_jwt tokens">
    Add a mechanism to issue short-lived `op_jwt` tokens (max 5 minutes) for your users from your identity provider. The JWT must be issued by the same IdP configured for your Magic application.

    <Info>
      Generate `op_jwt` as close to the signing call as possible to minimize its validity window.
    </Info>
  </Step>

  <Step title="Update database schema">
    Stop storing `recovery_key` for new v2 wallets. You only need `wallet_id` and `access_key`.

    Once a wallet is migrated, its `recovery_key` is permanently invalidated — recovery is handled by your identity provider going forward. You can safely delete stored `recovery_key` values from your database after migration.
  </Step>
</Steps>