Skip to main content

​
Base URL

All API requests should be made to:

​
Prerequisites

Before using Core API, you’ll need to:
1

Create a Magic Account

Visit the Magic Dashboard and sign up for a Magic developer account.
2

Create an Application

In your dashboard, create a new application and obtain your API keys.
3

Use your Secret Key

Your Secret Key will be used for all calls to the Core API.

​
Authentication

Core API requires authentication using your Magic secret key for all requests:
​
x-magic-secret-key
string
required
Your Magic secret key for service authentication. Format: sk_live_XXXXXXXX
This secret key should be treated as extremely sensitive, as it would allow anyone to trigger the creation of a wallet.

​
v2 Authorization Model

In addition to the secret key, v2 operations require a short-lived operation JWT (op_jwt).

​
Wallet Creation

When creating a wallet, pass auth_jwt — a JWT from your identity provider identifying the user. The enclave cryptographically binds the new wallet to this identity at creation time.

​
Signing Operations

Every signing request requires an op_jwt: a short-lived JWT for the specific user. The Nitro Enclave verifies this JWT offline against JWKS baked into the enclave image, confirms iss and sub exactly match the wallet’s binding, and authorizes the operation.

​
Supported Identity Providers

The enclave’s trust store is baked into the image at build time. The following provider families are supported:
  • Google (https://accounts.google.com)
  • Google Firebase (https://securetoken.google.com/<project>)
  • Auth0 (any tenant, e.g. https://<tenant>.us.auth0.com/)
  • AWS Cognito (any user pool, e.g. https://cognito-idp.<region>.amazonaws.com/<pool-id>)
  • Supabase (any project, e.g. https://<project>.supabase.co/auth/v1)
  • Stytch (any project)
To add support for your identity provider, contact Magic.
You must use a third-party identity provider. Self-issued or self-managed JWT issuers are not supported.

​
JWT Requirements

Both auth_jwt (wallet creation) and op_jwt (signing) must satisfy the following:
Claim / HeaderRequiredDetails
Issuer (iss)YesMust match a trusted issuer baked into the enclave. Captured at wallet creation and strictly matched on every signing call.
Subject (sub)YesMust be present and non-empty. Captured at wallet creation — must be byte-identical on every subsequent signing call for that wallet.
Expiry (exp)YesMust be present and not expired. For op_jwt, keep expiry to 5 minutes or less.
Issued at (iat)YesMust be present and must not be in the future.
Audience (aud)YesMust be present. Captured at wallet creation and matched on signing.
Algorithm (alg)YesMust be RS256 or ES256. none and symmetric algorithms are rejected.
Key ID (kid)YesRequired in the JWT header. Must resolve to a key in the enclave’s baked-in JWKS for that issuer.
JWTs with jku, x5u, x5c, or jwk header parameters are rejected outright to prevent key confusion attacks.
iss and sub are permanently captured at wallet creation. If either value changes in future tokens, all signing operations for that wallet will fail with a binding mismatch error.