After you set up the library for your project, you'll be able to use it to interact with the APIs, and add your own functionality. The first thing your app will need to do is to get a token to access the Admin API by performing the OAuth process. Learn more about OAuth on the Shopify platform.
Tip
If you are building an embedded app, we strongly recommend using Shopify managed installation with token exchange instead of the authorization code grant flow.
- Token Exchange
- Recommended for embedded apps
- Doesn't require redirects, which makes it faster and prevents flickering when loading the app
- Access scope changes are handled by Shopify if you use Shopify managed installation
- Authorization Code Grant Flow
- Suitable for non-embedded apps
- Installations, and access scope changes are managed by the app
OAuth process by exchanging the current user's session token for an access token to make authenticated Shopify API queries.
This can replace authorization code grant flow completely if you also take advantage of Shopify managed installation.
Learn more about:
- How token exchange works
- Using Shopify managed installation
- Configuring access scopes through the Shopify CLI
See "new embedded app authorization Strategy" to enable this feature.
- Ensure your access scopes are available on Shopify:
- configured through the Shopify CLI or
- install your app through the authorization code grant flow (not recommended)
- Start the token acquisition process by calling shopify.auth.tokenExchange to exchange user session token to access token.
- Use the exchanged session token to make authenticated API queries, see After OAuth
If your access scopes are configured through the Shopify CLI, scope changes will be handled by Shopify automatically. Learn more about Shopify managed installation. Using token exchange will ensure that the access token retrieved will always have the latest access scopes granted by the user.
If you don't have access scopes configured through the Shopify CLI, you can still use token exchange to exchange the current user's session token for access token.
Warning
This is not recommended because you'll have to manage both OAuth flows.
- Use authorization code grant flow to handle app installation so your app's access scopes will be available in Shopify.
- Once the app is installed for the user, you can use token exchange to exchange that user's session token to retrieve access token to refresh an expired token.
- Using token exchange will ensure you don't have to handle redirects through the authorization code grant flow on subsequent authorization calls, except when your requested access scopes changes.
Note
If you are building an embedded app, we strongly recommend using Shopify managed installation with token exchange instead of the authorization code grant flow.
To perform authorization code grant flow, you will need to create two endpoints in your app:
- Start the process by calling shopify.auth.begin to redirect the merchant to Shopify, to ask for permission to install the app.
- Return the merchant to your app once they approve the app installation, by calling shopify.auth.callback to set up a session with an API access token.
When the OAuth process is completed, the created session has a scope field which holds all of the access scopes that were requested from the merchant at the time.
When an app's access scopes change, it needs to request merchants to go through OAuth again to renew its permissions. The library provides an easy way for you to check whether that is the case at any point in your code:
const session: Session; // Loaded from one of the methods above
if (!shopify.config.scopes.equals(session.scope)) {
// Scopes have changed, the app should redirect the merchant to OAuth
}This is useful if you have a middleware or pre-request check in your app to ensure that the session is still valid.
Once you complete the OAuth process, you'll be able to call shopify.session.getCurrentId to fetch your session, and create API clients.
Note: private apps are unable to perform OAuth, because they don't require an access token to interact with API.