Exchange tokens
OAuth 2.0 token exchange (RFC 8693) allows apps to exchange a session token for an access token. The session token is only available for embedded apps and can be acquired using App Bridge.
This guide provides the endpoint and parameters for the token exchange API and explains how to implement token exchange manually.
How it works
Anchor link to section titled "How it works"The following sections list token exchange API details and request flow.
Token exchange API
Anchor link to section titled "Token exchange API"The following section details the endpoint and parameters for the token exchange API.
| Parameter | Description |
|---|---|
client_idRequired |
The API key for the app. |
client_secretRequired |
The client secret for the app. |
grant_typeRequired |
The value urn:ietf:params:oauth:grant-type:token-exchange indicates that token exchange is to be performed. |
subject_tokenRequired |
An ID token that represents the identity and active browser session of a merchant using the app. |
subject_token_typeRequired |
The value urn:ietf:params:oauth:token-type:id_token indicates that the subject token type is an ID token. |
requested_token_type |
Request flow using token exchange API
Anchor link to section titled "Request flow using token exchange API"The following diagram illustrates the token exchange flow from the point a merchant interacts with the app to the point the app receives an access token and can make authenticated API requests.
Requirements
Anchor link to section titled "Requirements"- You've created a Partner account.
- You've created an embedded app that doesn't use a Shopify app template.
- You have your app's client credentials.
- You're familiar with session tokens in Shopify.
Step 1: Ensure you have a valid session token
Anchor link to section titled "Step 1: Ensure you have a valid session token"Your app's frontend must acquire a session token from App Bridge. The app then includes it in the AUTHORIZATION header for all requests to the app's backend.
Your app's backend is responsible for authenticating all incoming requests using the session token.
Step 2: Get an access token
Anchor link to section titled "Step 2: Get an access token"If your app does not have a valid access token, it can exchange its session token for one using token exchange.
The following shows an example of a token exchange request and response for both an online and an offline access token.
If your session token is expired or otherwise invalid, then the token exchange request fails with an HTTP status code of 400 Bad Request.
Online access token response values
Anchor link to section titled "Online access token response values"| Value | Description |
|---|---|
access_token |
An API access token that can be used to access the shop’s data. Your app should store the token somewhere to make authenticated requests for a shop’s data. An online access token can be used for as long as the app is installed or for the next 24 hours, whichever comes first. After 24 hours, you need to refresh the access token. |
scope |
The list of access scopes that were granted to your app and are associated with the access token. |
expires_in |
The number of seconds until the access token expires. |
associated_user_scope |
The list of access scopes that were granted to the app and are available for this access token, given the user’s permissions. |
associated_user |
Information about the user who completed the authorization. The email field in this response appears regardless of the email verification status. If you’re using emails as an identification source, then make sure that the email_verified field is also true. You can use the id field to uniquely identify a single user. |
Offline access token response values
Anchor link to section titled "Offline access token response values"| Value | Description |
|---|---|
access_token |
An API access token that can be used to access the shop’s data as long as your app is installed. Your app should store the token somewhere to make authenticated requests for a shop’s data. An offline access token can be used for as long as the app is installed. |
scope |
The list of access scopes that were granted to your app and are associated with the access token. |
Step 3: Make authenticated requests
Anchor link to section titled "Step 3: Make authenticated requests"After your app has obtained an API access token, it can make authenticated requests to the GraphQL Admin API or REST Admin API and fulfill incoming requests from the app frontend.
The following examples show how to retrieve a list of products using the GraphQL Admin API and the REST Admin API.