> Tip: > You can use [Shopify CLI](/docs/apps/build/cli-for-apps) to generate a starter app with boilerplate code that handles authentication and authorization. The starter app includes code for an embedded app that uses [session tokens](/docs/apps/build/authentication-authorization/session-tokens) and [token exchange](/docs/apps/build/authentication-authorization/access-tokens/token-exchange). ## Requirements - You've created a [Partner account](https://www.shopify.com/partners). - You've created an embedded app that doesn't use a Shopify app template. - You have your app's [client credentials](/docs/apps/build/authentication-authorization/client-secrets). - You're familiar with [session tokens](/docs/apps/build/authentication-authorization/session-tokens) in Shopify. ## Step 1: Ensure you have a valid session token Your app's frontend must [acquire a session token from App Bridge](/docs/apps/build/authentication-authorization/session-tokens/set-up-session-tokens). 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](/docs/apps/build/authentication-authorization/session-tokens#request-flow-using-a-session-token) all incoming requests using the session token. ## Step 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](/docs/apps/build/authentication-authorization/access-tokens/token-exchange). ### Token exchange API ```http POST https://{shop}.myshopify.com/admin/oauth/access_token ``` <table> <caption>Parameters for the token exchange API and their descriptions</caption> <thead> <tr> <th scope="col">Parameter</th> <th scope="col">Description</th> </tr> </thead> <tbody> <tr> <td scope="row"><code>client_id</code><span class="heading-flag">Required</span></td> <td>The API key for the app.</td> </tr> <tr> <td scope="row"><code>client_secret</code><span class="heading-flag">Required</span></td> <td>The client secret for the app.</td> </tr> <tr> <td scope="row"><code>grant_type</code><span class="heading-flag">Required</span></td> <td>The value <code>urn:ietf:params:oauth:grant-type:token-exchange</code> indicates that token exchange is to be performed.</td> </tr> <tr> <td scope="row"><code>subject_token</code><span class="heading-flag">Required</span></td> <td>An ID token that represents the identity and active browser session of a merchant using the app.</td> </tr> <tr> <td scope="row"><code>subject_token_type</code><span class="heading-flag">Required</span></td> <td>The value <code>urn:ietf:params:oauth:token-type:id_token</code> indicates that the subject token type is an ID token.</td> </tr> <tr> <td scope="row"><code>requested_token_type</code></td> <td> <ul> <li><code>urn:shopify:params:oauth:token-type:offline-access-token</code> (default) for requesting <a href="/docs/apps/build/authentication-authorization/access-tokens/offline-access-tokens">offline</a> access tokens</li> <li><code>urn:shopify:params:oauth:token-type:online-access-token</code> for requesting <a href="/docs/apps/build/authentication-authorization/access-tokens/online-access-tokens">online</a> access tokens</li> </ul> </td> </tr> </tbody> </table> ### Example The following shows an example of a token exchange request and response for both an [online](/docs/apps/build/authentication-authorization/access-tokens/online-access-tokens) and an [offline](/docs/apps/build/authentication-authorization/access-tokens/offline-access-tokens) access token. <p> <div class="react-stacked-code-block ThemeMode-dim" data-preset="stacked"> <p> <div class="react-code-block" data-preset="file"> <div class="react-code-block-preload ThemeMode-dim"> <div class="react-code-block-preload-bar "></div> <div class="react-code-block-preload-placeholder-container"> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> </div> </div> <script data-option="filename" data-value="Request"></script> <script type="text/plain" data-language="curl" data-title="Online access token"> RAW_MD_CONTENTcurl -X POST \ https://{shop}.myshopify.com/admin/oauth/access_token \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "client_id": "{client_id}", "client_secret": "{client_secret}", "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "subject_token": "{session_token}", "subject_token_type": "urn:ietf:params:oauth:token-type:id_token", "requested_token_type": "urn:shopify:params:oauth:token-type:online-access-token" }' END_RAW_MD_CONTENT</script> <script type="text/plain" data-language="curl" data-title="Offline access token"> RAW_MD_CONTENTcurl -X POST \ https://{shop}.myshopify.com/admin/oauth/access_token \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "client_id": "{client_id}", "client_secret": "{client_secret}", "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "subject_token": "{session_token}", "subject_token_type": "urn:ietf:params:oauth:token-type:id_token", "requested_token_type": "urn:shopify:params:oauth:token-type:offline-access-token" }' END_RAW_MD_CONTENT</script> </div> </p> <p> <div class="react-code-block" data-preset="file"> <div class="react-code-block-preload ThemeMode-dim"> <div class="react-code-block-preload-bar "></div> <div class="react-code-block-preload-placeholder-container"> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> </div> </div> <script data-option="filename" data-value="Response"></script> <script type="text/plain" data-language="json" data-title="Online access token"> RAW_MD_CONTENT{ "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 } } END_RAW_MD_CONTENT</script> <script type="text/plain" data-language="json" data-title="Offline access token"> RAW_MD_CONTENT{ "access_token": "f85632530bf277ec9ac6f649fc327f17", "scope": "write_orders,read_customers" } END_RAW_MD_CONTENT</script> </div> </p> </div> </p> If your session token is expired or otherwise invalid, then the token exchange request fails with an HTTP [status code](/docs/api/usage/response-codes.md) of `400 Bad Request`. ### 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](/docs/apps/build/authentication-authorization/access-tokens/online-access-tokens) 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 | 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](/docs/apps/build/authentication-authorization/access-tokens/offline-access-tokens) 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 After your app has obtained an API access token, it can make authenticated requests to the [GraphQL Admin API](/docs/api/admin-graphql) and fulfill incoming requests from the app frontend. The following example shows how to retrieve a list of products using the [GraphQL Admin API](/docs/api/admin-graphql). <p> <div class="react-code-block" data-preset="terminal"> <div class="react-code-block-preload ThemeMode-dim"> <div class="react-code-block-preload-bar "></div> <div class="react-code-block-preload-placeholder-container"> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> <div class="react-code-block-preload-code-container"> <div class="react-code-block-preload-codeline-number"></div> <div class="react-code-block-preload-codeline"></div> </div> </div> </div> <script data-option="title" data-value="Terminal"></script> <script type="text/plain" data-language="curl" data-title="GraphQL"> RAW_MD_CONTENTcurl -X POST \ https://{shop}.myshopify.com/admin/api/2025-01/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "{ products(first: 5) { edges { node { id handle } } pageInfo { hasNextPage } } }" }' END_RAW_MD_CONTENT</script> </div> </p>