Developer Docs

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

Update wallet creation

Replace encryption_context with auth_jwt — the user’s JWT from your identity provider.v1:

cURL

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:

cURL

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

v2 wallet creation no longer returns a recovery_key. You only need to store wallet_id and access_key.

Update signing operations

Replace encryption_context with op_jwt. The access_key and wallet_id remain the same.v1:

cURL

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:

cURL

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

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.

Generate op_jwt as close to the signing call as possible to minimize its validity window.

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.

Server Wallets

Express API

Core API

Migrating from v1 to v2

What’s Happening

What Changed

Migration Steps

​What’s Happening

​What Changed

​Migration Steps

What’s Happening

What Changed

Migration Steps