Exchange a session token for an access token

Anchor to RequirementsRequirements

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

Anchor to Step 1: Ensure you have a valid session tokenStep 1: Ensure you have a valid session token

Your app's frontend must acquire a session token from App Bridge. In the current version of App Bridge, this is handled automatically using authenticatedFetch. You must include the token 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.

Anchor to Step 2: Get an access tokenStep 2: Get an access token

If your app doesn't have a valid access token, then it can exchange its session token for an access token using token exchange.

Anchor to Token exchange APIToken exchange API

Anchor to ExampleExample

The following shows an example of a token exchange request and response for both an online and an offline access token.

curl -X POST \
  https://{shop}.myshopify.com/admin/oauth/access_token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -d 'client_id={client_id}' \
  -d 'client_secret={client_secret}' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  -d 'subject_token={session_token}' \
  -d 'subject_token_type=urn:ietf:params:oauth:token-type:id_token' \
  -d 'requested_token_type=urn:shopify:params:oauth:token-type:online-access-token'

curl -X POST \
  https://{shop}.myshopify.com/admin/oauth/access_token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -d 'client_id={client_id}' \
  -d 'client_secret={client_secret}' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  -d 'subject_token={session_token}' \
  -d 'subject_token_type=urn:ietf:params:oauth:token-type:id_token' \
  -d 'requested_token_type=urn:shopify:params:oauth:token-type:offline-access-token' \
  -d 'expiring=1'

curl -X POST \
  https://{shop}.myshopify.com/admin/oauth/access_token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -d 'client_id={client_id}' \
  -d 'client_secret={client_secret}' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  -d 'subject_token={session_token}' \
  -d 'subject_token_type=urn:ietf:params:oauth:token-type:id_token' \
  -d 'requested_token_type=urn:shopify:params:oauth:token-type:offline-access-token'

{
  "access_token": "f85632530bf277ec9ac6f649fc327f17",
  "scope": "write_orders,read_customers",
  "expires_in": 86399,
  "associated_user_scope": "write_orders",
  "associated_user": {
    "id": 902541635,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "email_verified": true,
    "account_owner": true,
    "locale": "en",
    "collaborator": false
  }
}

{
  "access_token": "f85632530bf277ec9ac6f649fc327f17",
  "scope": "write_orders,read_customers",
  "expires_in": 3600,
  "refresh_token": "shprt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "refresh_token_expires_in": 7776000
}

{
  "access_token": "f85632530bf277ec9ac6f649fc327f17",
  "scope": "write_orders,read_customers"
}

If your session token is expired or otherwise invalid, then the token exchange request fails with an HTTP status code of 400 Bad Request.

Anchor to Online access token response valuesOnline access token response values

Anchor to Offline access token response valuesOffline access token response values

* Only included when expiring=1 is specified in the request.

Anchor to Step 3: Make authenticated requestsStep 3: Make authenticated requests

After your app has obtained an API access token, it can make authenticated requests to the GraphQL Admin API and fulfill incoming requests from the app frontend.

The following example shows how to retrieve a list of products using the GraphQL Admin API.