Introduction to Shopify OAuth 2.0 Authentication
For developers building custom apps or public applications for the Shopify App Store, understanding the OAuth 2.0 flow is fundamental. An access token is the key that allows your application to interact with a merchant's store data via the Shopify Admin API. Without a valid token, your app cannot read products, manage orders, or update inventory.
Shopify uses the OAuth 2.0 authorization code grant flow to provide secure, delegated access. This ensures that merchants never have to share their login credentials with third-party developers. Instead, they grant specific permissions (scopes) to your app, and Shopify issues a unique token in return. In this guide, we will walk through the step-by-step process of implementing this flow in your application backend.
Step 1: Setting Up Your Shopify App Credentials
Before you can initiate the OAuth flow, you must have a Shopify Partner account and an app created within the Partner Dashboard. This provides you with the essential credentials required to identify your app to Shopify.
- Client ID (API Key): A public identifier for your application.
- Client Secret (API Secret Key): A private key used to sign requests and exchange codes for tokens. This must never be exposed on the client side.
- App Setup: You must configure a 'Redirection URL' in your app settings. This is the endpoint on your server where Shopify will send the user after they authorize your app.
Once you have these credentials, you are ready to begin the handshake process by redirecting the merchant to the Shopify authorization screen.
Step 2: Redirecting the Merchant to the Installation Screen
The flow begins when a merchant attempts to install your app or when you manually trigger the installation process. You must redirect the user's browser to the Shopify authorization endpoint. The URL structure looks like this:
https://{shop}.myshopify.com/admin/oauth/authorize?client_id={client_id}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}&grant_options[]={access_mode}Understanding the Query Parameters
client_id: Your app's API Key.scope: A comma-separated list of permissions your app needs (e.g.,read_products,write_orders).redirect_uri: The URL where the merchant is sent after granting permission. It must match the URL saved in your Partner Dashboard.state: A unique, randomly generated string (nonce) used to prevent Cross-Site Request Forgery (CSRF) attacks.grant_options[]: Useper-userfor online access tokens or leave empty for offline (permanent) access tokens.
When the merchant visits this URL, they will see a screen detailing the permissions your app is requesting. Once they click 'Install App', Shopify redirects them back to your server.
Step 3: Verifying the Callback and Security Checks
After the merchant approves the installation, Shopify redirects the browser to your specified redirect_uri. This request includes several query parameters: code, hmac, host, shop, state, and timestamp.
Security is paramount at this stage. You must perform two critical checks before proceeding:
- Nonce Verification: Ensure the
stateparameter matches the nonce you generated in Step 2. If they do not match, the request may be malicious. - HMAC Validation: Shopify signs every request with an HMAC (Hash-based Message Authentication Code). You must calculate the HMAC of the query parameters using your Client Secret and compare it to the
hmacparameter provided by Shopify.
If the HMAC is valid, you can trust that the request originated from Shopify and that the code (the authorization code) is legitimate.
Step 4: Exchanging the Authorization Code for an Access Token
The authorization code provided in the previous step is short-lived and can only be used once. To get the permanent (or session-based) access token, your server must make a POST request to the store's access token endpoint.
The request should be sent to: https://{shop}.myshopify.com/admin/oauth/access_token with the following JSON body:
{
"client_id": "YOUR_API_KEY",
"client_secret": "YOUR_API_SECRET",
"code": "THE_AUTHORIZATION_CODE"
}Upon a successful request, Shopify will return a JSON response containing the access token:
{
"access_token": "shpat_xxxxxxxxxxxxxxxxxxxx",
"scope": "read_products,write_orders",
"associated_user_scope": null,
"associated_user": null
}You should store this access_token securely in your database. This token is what you will include in the X-Shopify-Access-Token header for all future API calls to that specific merchant's store.
Types of Access Tokens: Online vs. Offline
It is important to distinguish between the two types of access tokens Shopify offers. By default, Shopify issues offline access tokens. These are ideal for background tasks, such as syncing inventory or processing webhooks, because they do not expire unless the app is uninstalled.
Online access tokens are linked to a specific user session and expire when the user logs out or the session ends. These are useful for embedded apps where you want to ensure the app's permissions are tied directly to the logged-in staff member's permissions. You can request an online token by including grant_options[]=per-user in your initial authorization redirect.
Conclusion
Implementing OAuth 2.0 for Shopify is a structured process that ensures the highest level of security for both developers and merchants. By following these steps—setting up credentials, redirecting for consent, verifying the HMAC, and exchanging the code for a token—you can build robust applications that integrate seamlessly with the Shopify ecosystem. Remember to always store your access tokens and client secrets securely, and never expose them in client-side code. With your access token in hand, you are now ready to harness the full power of the Shopify Admin API.
