About app authentication

Shopify apps call the GraphQL Admin API to read and write store data on behalf of merchants. Before your app can make those calls, it needs to authenticate: prove which app is calling, which merchant approved it, and what the app is allowed to do.

This section covers how that authentication works for apps calling the GraphQL Admin API, and points you to the setup path for the kind of app you're building. Other Shopify APIs issue their own token types and use their own headers, so if you're authenticating requests to the Storefront API or the Customer Account API, see Shopify API authentication instead. You don't implement OAuth by hand for most apps. Shopify CLI and the Shopify app templates handle the token flow for you.

Anchor to What you can doWhat you can do

• Call the GraphQL Admin API as an installed app, scoped to the permissions a merchant approved.
• Call the GraphQL Admin API directly from your app's frontend with Direct API access, where App Bridge authenticates each request.
• Run background jobs and scheduled tasks, and subscribe to webhooks, using an offline access token that persists across sessions.
• Attribute actions to a specific staff member and enforce per-user permissions using online access tokens.
• Give a subsystem limited, scoped access to Shopify APIs without sharing your app's full credentials, using delegate access tokens.

Anchor to How it worksHow it works

For any app with a backend of its own, authentication follows the same three steps:

1. Your app gets an access token for the store it's calling.
2. Your app sends the token in the X-Shopify-Access-Token header on every GraphQL Admin API request.
3. Shopify returns the data the token's access scopes allow, or an error if the token is missing, invalid, or lacks a required scope.

What differs is how your app gets that token. Most apps get one after a merchant installs the app and approves the scopes it requests. An app that only works with stores in your own organization requests one directly, with no merchant install. An extension-only app has no backend, so it never holds a token at all (Shopify authenticates its requests for it through Direct API access).

Choosing an approach maps each option to its setup guide.

Anchor to Key terminologyKey terminology

These terms come up across Shopify's authentication flows and throughout the rest of this section.

Anchor to Authentication and authorizationAuthentication and authorization

Authentication proves which identity is making a request. Authorization determines what that identity is allowed to do. On each API request, the access token does both: it identifies your app, and its access scopes determine what it can access.

Some flows authenticate a user first. For example, embedded apps validate an ID token, then exchange it for an access token.

Anchor to Access tokenAccess token

The credential your code sends on each GraphQL Admin API request, in the X-Shopify-Access-Token header. Online or offline describes a token's lifetime: online tokens last as long as a staff member's session, while offline tokens persist across sessions. See access tokens.

Anchor to ID tokenID token

A short-lived JWT that proves a request comes from an authenticated Shopify user. App Bridge issues one to the frontend of an app running inside the Shopify admin, and your app usually exchanges it for an access token rather than sending it to an API. App Bridge 2.0 and older documentation call the same credential a session token. See ID tokens, or Set up session tokens with App Bridge 2.0 if that's the version your app uses.

Anchor to GrantGrant

The OAuth flow your app uses to get an access token. Shopify supports three, and which one applies depends on where your app runs and whose stores it acts on:

• Token exchange, for apps that run inside the Shopify admin. Your app exchanges an ID token for an access token without redirecting the merchant.
• Authorization code grant, for apps that run outside the Shopify admin. The merchant is redirected to Shopify to approve access, then back to your app with a code that your app exchanges for an access token.
• Client credentials grant, for apps that act only on stores in your own organization. Your app authenticates as itself with its client ID and client secret, and there's no merchant approval step.

Choosing an approach maps each grant to its setup guide.

Anchor to Shopify managed installationShopify managed installation

The installation method where Shopify installs your app and updates its access scopes without calling your app. You declare the scopes your app needs in its shopify.app.toml configuration file and push it to Shopify, which then handles the merchant's approval. Apps built with Shopify CLI use managed installation by default, which is why they don't implement the authorization code grant.

Anchor to Client ID and client secretClient ID and client secret

The credentials that identify your app, issued when you create it. The client ID is public. The client secret isn't: it proves a request comes from your app, so keep it server-side and never ship it in client code. Don't confuse them with the client credentials grant, which is one of the flows that uses them. See manage your app credentials.

Anchor to Access scopesAccess scopes

The permissions a merchant grants, such as read_products or write_orders. Scopes determine what an access token can do. Any permission to write a resource includes permission to read it, so request the write scope only when your app needs both. See manage access scopes.

Anchor to Choosing an approachChoosing an approach

Most apps are embedded, meaning they run inside the Shopify admin, and building one with Shopify CLI is the recommended path. Apps that aren't embedded might run outside the Shopify admin, or act only on stores in your own organization.

How your app gets an access token depends on where it runs and whose stores it acts on, and an app with no backend of its own doesn't get one at all:

Every option except the client credentials grant works on any merchant's stores, including your clients'. For information about getting your app onto stores outside your own organization, see About app distribution.

Whichever of the four token routes you use, the token you end up with and the GraphQL Admin API calls you make with it are the same.