Shopify API authentication
In order to keep transactions on Shopify’s platform safe and secure, all apps connecting with our APIs must authenticate when making API calls. Some resources, like Storefront API, make a limited subset of store data available to unauthenticated end users.
Types of authentication
There are two methods of authenticating apps and services with Shopify’s platform:
Any web application or service that connects with Shopify’s platform is referred to as an app, regardless of how it’s exposed to end users. Different types of apps use different authentication methods.
Be sure you understand the differences between the two types of authentication schemes before you begin your development process.
- Authenticate with OAuth
- Authenticate a public app with OAuth
- Authenticate a custom app with OAuth
- Authenticate a private app with the Shopify admin
Shopify’s Storefront API is unauthenticated, which means that certain data can be accessed by users without a username or password. You should use the Storefront API only if you are comfortable with this risk, and you should limit which store data can be accessed. Data access is controlled by the permissions that you choose when you create a storefront access token. After you've created a storefront access token, you can change its API permissions as needed.
API access modes
When you create a token, you can choose between two different access modes:
The appropriate access mode for your token depends on your app's use case.
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. This type of access mode 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.
- This access mode must be explicitly requested in the authorization phase.
- An API request made using an online mode access token is guaranteed to respect the user's individual permissions. Shopify returns a
403 Forbiddenstatus 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.
- An access token created with this access mode is temporary, and is guaranteed to expire after some amount of time.
- After an access token has expired, Shopify returns a
401 Unauthorizedresponse 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.
- It's recommended to keep tokens with online access in a user's temporary session storage, backed by a cookie in the user's browser, and to make API requests using this access token in response to the user's requests.
- If your app implements caching to avoid fetching data from Shopify too often, then make sure to scope the cache to each individual user. Since 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.
- 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.
- After your app is installed, requesting this access mode will always return an access token restricted to the scopes available to the user. The app can inspect
associated_user_scopeto determine if a user is lacking certain permissions.
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.
- This is the default access mode when none is specified.
- The access tokens created with this access mode are permanent. They are revoked only when the app is uninstalled from a store.
- This access mode is suitable when no user interaction is involved.
- Authorizing an app multiple times with offline access returns the same access token each time. After obtaining offline access to a store, it is only necessary to re-authorize an app after it has been uninstalled, or when it needs additional access scopes.
- When this 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 are able to successfully complete the OAuth flow again, regardless of their permission levels.