Access modes
When you create an API access token for the Shopify Admin API during the OAuth flow, you can choose between two access modes: offline and online. This guide describes the differences between online and offline access modes.
The appropriate access mode for your token depends on your app’s use case. It’s also possible for an app to use both access modes at the same time, by using different tokens when appropriate.
Offline access
Anchor link to section titled "Offline access"Offline is the default access mode when none is specified. Tokens with offline access mode are meant for long-term access to a store, where no user interaction is involved. Offline access mode is ideal for background work in response to webhooks, or for maintenance work in backgrounded jobs.
Installation
Anchor link to section titled "Installation"When offline mode is requested and the app is not already installed in a store, the user installing the app must have access to all required scopes or the installation will fail.
After the app is installed on a store, all users with Apps staff permissions can successfully complete the OAuth flow again, regardless of their permission levels.
Authorization
Anchor link to section titled "Authorization"Authorizing an app multiple times with offline access returns the same access token each time. After obtaining offline access to a store, it's necessary to reauthorize an app only after it has been uninstalled, or when it needs additional access scopes.
Revoking access
Anchor link to section titled "Revoking access"The access tokens created with the offline access mode are permanent. They are revoked only when the app is uninstalled from a store.
Online access
Anchor link to section titled "Online access"Online access must be explicitly requested during the authorization phase of OAuth. Tokens with online access mode are linked to an individual user on a store, where the access token's lifespan matches the lifespan of the user's web session.
Online access is meant to be used when a user is interacting with your app through the web, or when an app must respect an individual user's permission level.
Example use cases
Anchor link to section titled "Example use cases"- Your app's security requirements specify short-lived access to a store. Tokens with online access mode expire either when the user logs out or after 24 hours.
- Your app differentiates between users that are logged in and those using the app. Tokens with online access mode have the same permissions as the user that's logged in.
Installation
Anchor link to section titled "Installation"After your app is installed, requesting this access mode always returns an access token restricted to the scopes available to the user. The app can inspect scope
and associated_user_scope
to determine if a user is lacking certain permissions.
When online access mode is requested and the app is not already installed on a store, the user installing the app must have access to all required scopes, or the installation fails.
Authorization
Anchor link to section titled "Authorization"An API request made using an online mode access token is guaranteed to respect the user's individual permissions. Shopify returns a 403 Forbidden
status code when the access token is valid but the user does not have access.
App developers should make sure to handle such a response gracefully. After an access token has expired, Shopify returns a 401 Unauthorized
response code.
Best practices
Anchor link to section titled "Best practices"If your app implements caching to avoid fetching data from Shopify too often, then make sure to scope the cache to each individual user. Because online access mode is guaranteed to respect each user's permission level, not caching on a per-user basis could result in an inconsistent cache.
Revoking access
Anchor link to section titled "Revoking access"The access tokens created with the online access mode are temporary, and are guaranteed to expire after some time. After an access token has expired, Shopify returns a 401 Unauthorized
response code.
Users can revoke their own access to your app at any time, without affecting the validity of other users' access tokens. When a user logs out of Shopify admin, all online mode access tokens created during the same web session are revoked.
- Authenticate your app with OAuth.
- Authenticate your admin-created custom app in the Shopify admin.
- Authenticate your embedded app using session tokens.