Skip to main content

​
Introduction

When a user signs in with Dynamic, your client receives multiple JSON Web Token (JWTs). After authentication Dynamic issues both an access token and an id token. To trust the user’s identity on your backend, you must verify the access token on the server before using any claims. Client-sent tokens cannot be trusted until they are cryptographically verified.

​
Types

​
Access Tokens (minJwt)

The access token JWT is the session credential — it grants the user access to protected resources like wallets and user data on Dynamic’s servers and can be used by customers to validate access on customer servers if utilizing Dynamic as the authentication provider for your app.

​
ID Tokens (jwt)

The ID token JWT is meant to be used by the client application only. The id token contains claims about the authenticated user which can be verified by the application

​
JWT structure

A JWT has three parts: header, payload (claims), and signature. Dynamic signs JWTs with RS256 (RSA signature with SHA-256). The signing key is unique per environment, so you use the public key for your environment to verify that the token was issued by Dynamic and has not been tampered with.

​
Standard claims

Dynamic’s JWTs include standard JWT claims:
ClaimDescription
issIssuer. Dynamic sets this to the issuer for your environment (e.g. app.dynamic.xyz/<environment_id>).
audAudience. Intended audience for the token.
subSubject. The Dynamic user ID.
iatIssued at. Unix timestamp when the token was issued.
expExpiration. Unix timestamp when the token expires.
sidSession Id. The unique identifier for the Dynamic session

​
Dynamic-specific claims

The payload may also include Dynamic-specific claims. These fields are optional and depend on whether you collect the information during onboarding:
ClaimDescription
aliasAlias from customer information capture.
emailEmail from customer information capture.
environment_idUnique ID of the project environment (from the dashboard API).
given_nameFirst name from customer information capture.
family_nameLast name from customer information capture.
listsNames of access lists enabled for this user. See Access Control.
verified_credentialsList of all verified credentials connected to this user.
verified_accountIf present, the most recently signed and verified account.

​
Example payload

{
  "alias": "john",
  "aud": "https://dashboard.hello.xyz",
  "verified_credentials": [
    {
      "address": "0x000123abc",
      "chain": "eip155",
      "id": "af615228-99e5-48ee-905d-4575f0a6bfc9",
      "wallet_name": "metamask"
    }
  ],
  "email": "[email protected]",
  "environment_id": "fb6dd9d1-09f5-43c3-8a8c-eab6e44c37f9",
  "family_name": "bot",
  "given_name": "jon",
  "iss": "app.dynamic.xyz/fb6dd9d1-09f5-43c3-8a8c-eab6e44c37f9",
  "lists": ["Community dashboard access list"],
  "sub": "d261ee91-8ea0-4949-b8bb-b6ab4f712a49",
  "verified_account": {
    "address": "0x000123abc",
    "chain": "eip155",
    "id": "af615228-99e5-48ee-905d-4575f0a6bfc9",
    "wallet_name": "metamask"
  },
  "iat": 1660677597,
  "exp": 1660684797
}

​
Token storage

The JWT is stored either in a cookie or in in-app storage (e.g. browser or device storage), depending on your project’s auth storage settings:
  • Cookie storage: The browser sends the token to your backend automatically on same-origin requests. The app cannot read the token directly — your backend should rely on the cookie for auth.
  • In-app storage: The app can read the token and send it explicitly (e.g. in an Authorization: Bearer <token> header). Use this when you need to pass the JWT to your backend or third-party integrations.

​
Getting the verification key

To verify a Dynamic-issued JWT, you need the public key for your environment. You can get it in two ways:
  1. Developer Dashboard — In the API tab of your developer dashboard, you can find the public key for your environment.
  2. JWKS endpoint — Dynamic exposes a JWKS (JSON Web Key Set) endpoint so your server can fetch the public key(s) used to sign tokens: 
    GET https://app.dynamic.xyz/api/v0/sdk/{environmentId}/.well-known/jwks
    Replace {environmentId} with your environment ID (from the dashboard). Your JWT library can use this URL to resolve the key by the kid (key ID) in the JWT header. See the Find JWKS for public key API reference.
Any backend stack can call this endpoint or use the dashboard key; no SDK is required.

​
Verifying the JWT

Regardless of which Dynamic SDK you use on the client (React, React Native, Flutter, Swift, Kotlin, JavaScript, etc.), your backend verifies the same Dynamic-issued JWT the same way:
  1. Client gets the JWT from Dynamic (the way you obtain it depends on your SDK — e.g. getAuthToken(), sdk.auth.token, etc.).
  2. Client sends the JWT to your backend (e.g. in the Authorization: Bearer <token> header).
  3. Backend verifies the JWT using Dynamic’s public key (signature and claims).
  4. Backend uses the verified claims (e.g. sub for user ID, verified_credentials) to authorize the request.
On your backend, after you receive the JWT:
  1. Verify the signature — Decode the JWT and verify the signature using the public key (RS256). If verification fails, reject the request.
  2. Validate claims — Ensure:
    • iss matches the issuer for your environment (e.g. app.dynamic.xyz/<environment_id>).
    • exp is in the future and iat is reasonable (token not expired, not from the future).
    • aud if you use audience restrictions.
  3. Optional: handle scopes — Dynamic may include a scopes claim. For example, requiresAdditionalAuth indicates the user must complete additional verification (e.g. MFA) before the token is fully trusted. Reject or handle such tokens according to your policy.
No Dynamic SDK is required on the server. Use any JWT library that supports RS256 and (if you use the JWKS URL) JWKS key resolution — e.g. in Node (jsonwebtoken + jwks-rsa), Python (PyJWT), Go (jwt-go), etc.

​
Security

Follow Dynamic’s security guidance for tokens:
  • Configure JWT lifetime to the shortest acceptable duration to balance security and user experience. The maximum is 30 days. See dashboard security settings.
  • Never save or log user JWTs.
  • Consider cookie-based authentication to reduce session hijacking risk by making the JWT inaccessible to client-side scripts.
  • Store API keys on the backend only — never expose them on the client side.
  • Never send Id tokens to the server. Only access tokens.
For more, see the Security overview and Best Practices.

​
SDK-specific guides

How you obtain the JWT on the client depends on your SDK:

​
Frameworks

​
API reference