ID tokens
An ID token, previously called a session token, is a short-lived JWT that App Bridge issues to your embedded app to prove a request comes from an authenticated Shopify user. Your app exchanges it for an access token and never sends it to a Shopify API.
This page explains what an ID token authenticates, how it differs from an access token, the claims your app validates, and where it fits in the authentication flow.
Apps embedded in the Shopify admin must authenticate with ID tokens, because third-party cookies aren't reliably available in that context. If your app still relies on cookies in a way that could put merchants at risk, you might be contacted during Shopify's app quality checks and asked to migrate. This request requires immediate action.
Apps embedded in the Shopify admin must authenticate with ID tokens, because third-party cookies aren't reliably available in that context. If your app still relies on cookies in a way that could put merchants at risk, you might be contacted during Shopify's app quality checks and asked to migrate. This request requires immediate action.
Anchor to What an ID token doesWhat an ID token does
An ID token and an access token do two different jobs:
- ID token: Authenticates the user. It proves that a logged-in Shopify user is making the request from a specific store. It carries no permissions, and you can't use it to call a Shopify API.
- Access token: Authenticates your app. It proves your app is allowed to call the API, and its access scopes determine what your app can read and write.
Your app gets the ID token first, then exchanges it for an access token. The ID token is how Shopify vouches for the user, and the access token is what your app sends on every GraphQL Admin API request.
Anchor to How ID tokens workHow ID tokens work
When a merchant opens your embedded app, the ID token flows through your app before any API call:
- App Bridge issues an ID token to your app's frontend.
- Your frontend sends the ID token to your backend.
- Your backend validates the token's claims, then exchanges it for an access token. For the endpoint and parameters, see how token exchange works.
- Your app calls the GraphQL Admin API with the access token. The ID token is never sent to the API.
ID tokens are short-lived: they expire one minute after they're issued, so your app fetches a fresh one for each request rather than caching it. App Bridge may return a cached token with less than the full minute remaining, so don't assume a freshly fetched token has its entire lifetime left. Standalone apps that run outside the Shopify admin can't use App Bridge, so they get access tokens through the authorization code grant instead.
Ad blockers can sometimes block App Bridge from issuing an ID token. If your app's Shopify App Store review stalls on the automated authentication check, disable your ad blocker and reopen your app so the check can observe it fetching a token.
Ad blockers can sometimes block App Bridge from issuing an ID token. If your app's Shopify App Store review stalls on the automated authentication check, disable your ad blocker and reopen your app so the check can observe it fetching a token.
Anchor to ID token claimsID token claims
Shopify app templates validate ID tokens for you, so most apps don't check claims manually. If you validate tokens yourself, such as in a custom backend, check the token's signature against your client secret using HS256 (HMAC-SHA256), then check the following claims. If any check fails, reject the request with a 401 before calling the token endpoint.
| Claim | What to check |
|---|---|
exp | The expiry time. Must be in the future. |
nbf | The not-before time. Must be in the past. |
aud | The audience. Must match your app's client ID. |
iss and dest | The issuer and destination. Their hostnames must match. |
An ID token also carries claims that identify the user and session. You don't validate these, but your app can read them:
| Claim | Description |
|---|---|
sub | The user the token was issued for. |
sid | A session ID, unique per user and app. |
jti | A secure random UUID for the token. |
iat | When the token was issued. |
Anchor to Example decoded payloadExample decoded payload
The following payload shows both claim sets as your app receives them after decoding an ID token. All times are UNIX timestamps.
Anchor to Uses beyond token exchangeUses beyond token exchange
In most cases, you exchange the ID token for an access token and don't use it directly. App Bridge's fetch interceptor adds the ID token to requests to your app's domain automatically.
Call shopify.idToken() directly when you need the token outside a standard fetch request, such as authenticating a WebSocket connection to your backend. For runnable code, see the ID Token API reference.
Send ID tokens to your own backend only, never to a third-party service. Verifying the signature requires your client secret, so a third party can't check it unless you hand over a credential that also lets them mint tokens your app would accept. The token is a bearer credential, so anything holding a valid one can replay it against your backend until it expires.
Send ID tokens to your own backend only, never to a third-party service. Verifying the signature requires your client secret, so a third party can't check it unless you hand over a credential that also lets them mint tokens your app would accept. The token is a bearer credential, so anything holding a valid one can replay it against your backend until it expires.
Anchor to Next stepsNext steps
- Find the setup path for your app type in About app authentication.
- See how access tokens work, including token types and refreshing an expiring offline token.