Introduction to Shopify App Authentication
Building a Shopify app is an exciting venture for any developer, but before you can start displaying data or modifying store settings, you must master the gateway to the Shopify ecosystem: authentication. Authentication ensures that your app has the explicit permission of the merchant to access their store data and that every request made between your server and Shopify is secure.
In the early days of Shopify development, authentication was handled almost exclusively via server-side OAuth. However, as the platform evolved toward faster, more integrated experiences, Shopify introduced App Bridge and Session Tokens. Today, a modern Shopify app typically uses a hybrid approach: OAuth for the initial installation and Session Tokens for ongoing requests within the Shopify Admin. In this guide, we will break down the entire process into actionable steps to get your app authenticated and running.
Step 1: Setting Up Your Shopify Partner Account and App
Before writing a single line of authentication code, you need a place for your app to live within the Shopify infrastructure. This starts with the Shopify Partner Dashboard. If you haven't already, create a Partner account and navigate to the 'Apps' section to create a new app manually or via the Shopify CLI.
During the setup, you will be provided with two critical pieces of information:
- Client ID (API Key): This identifies your app to Shopify.
- Client Secret: This is used to sign requests and should never be shared publicly or committed to client-side code.
You must also configure your App Setup by defining your Allowed Redirection URLs. These are the endpoints on your server that Shopify will send the user back to after they approve your app installation. For local development, many developers use tools like Cloudflare Tunnel or Ngrok to create a secure HTTPS tunnel to their local machine.
Step 2: Initiating the OAuth Flow
The OAuth 2.0 flow is the standard protocol used to authorize your app. The process begins when a merchant attempts to install your app. Your server must redirect the merchant to Shopify's authorization endpoint. The URL structure looks like this:
https://{shop}.myshopify.com/admin/oauth/authorize?client_id={api_key}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}&grant_options[]={access_mode}In this URL, the scope parameter is a comma-separated list of permissions your app needs (e.g., read_products,write_orders). The nonce is a unique, random string used to prevent Cross-Site Request Forgery (CSRF) attacks. You should store this nonce in a cookie or session to verify it later in the process.
Step 3: Handling the Callback and Exchanging the Code
Once the merchant clicks 'Install', Shopify redirects them back to your specified redirect_uri with several query parameters, including code, shop, host, and hmac. Your first priority is security: you must verify the hmac signature to ensure the request actually came from Shopify.
To verify the HMAC, you take all query parameters (except hmac itself), sort them alphabetically, join them into a string, and hash them using your Client Secret. If the resulting hash matches the hmac parameter provided by Shopify, the request is authentic.
After verification, you must exchange the temporary code for a permanent access token. You do this by making a POST request to the shop's access token endpoint:
POST https://{shop}.myshopify.com/admin/oauth/access_token
{
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"code": "the_code_from_params"
}Shopify will respond with a JSON object containing the access_token. This token is what you will use in the header of all future REST or GraphQL API calls for that specific shop. Store this token securely in your database.
Step 4: Implementing Session Tokens for Embedded Apps
While OAuth is great for the initial handshake, embedded apps (apps that run inside the Shopify Admin iframe) face challenges with third-party cookies. To solve this, Shopify uses Session Tokens via App Bridge. Instead of relying on traditional browser sessions, your frontend requests a short-lived, signed JWT (JSON Web Token) from Shopify.
When your frontend makes a request to your app's backend, it includes this Session Token in the Authorization header:
Authorization: Bearer {session_token}Your backend server then decodes this token using your Client Secret. Because the token is signed by Shopify, you can trust the information inside it, such as the shop URL and the user ID, without needing to perform a full OAuth handshake every time a page loads. This creates a much faster and more reliable user experience.
Step 5: Managing Token Expiry and Re-authentication
Authentication is not a 'set it and forget it' task. Access tokens can become invalid if a merchant uninstalls and reinstalls your app, or if you need to request additional scopes. Your app must be built to handle 401 Unauthorized errors gracefully.
If your backend detects an invalid token, you should redirect the user back to the start of the OAuth flow. Similarly, if you are using Session Tokens, ensure your frontend is configured to refresh the token frequently (they typically expire every 60 seconds) using the App Bridge getSessionToken function.
Conclusion
Mastering Shopify app authentication is the foundation of a professional, secure application. By combining the robust security of OAuth 2.0 for installation with the modern efficiency of Session Tokens for embedded interaction, you ensure that your app remains compliant with Shopify's best practices. Remember to always prioritize security by verifying HMACs and never exposing your Client Secret. With these steps completed, you are ready to move on to the core functionality of your app and start providing value to Shopify merchants worldwide.
