OAuth

Public apps and custom apps must authenticate using the OAuth 2.0 specification to use Shopify’s API resources. This guide shows you how to authenticate a public or custom app using OAuth.

Requirements

• You've created a partner account and a development store.
• You understand how apps fit into Shopify and the different types of apps you can build.
• You're familiar with the different methods of authenticating apps and services with Shopify’s platform.

The OAuth flow

Shopify uses OAuth 2.0’s authorization code grant flow to issue access tokens on behalf of users. The following diagram illustrates the OAuth flow based on the actions of the merchant, your app, and Shopify.

1. The merchant makes a request to install the app.
2. The app redirects to Shopify to load the OAuth grant screen and requests the required scopes.
3. Shopify displays a prompt to the merchant to give authorization to the app, and prompts the merchant to log in if required.
4. The merchant consents to the scopes and is redirected to the redirect_uri.
5. The app makes an access token request to Shopify including the client_id, client_secret, and code.
6. Shopify returns the access token and requested scopes.
7. The app uses the access token to make requests to the Shopify API.
8. Shopify returns the requested data.

Session tokens for embedded apps

If you're using Shopify App Bridge to embed your app in the Shopify Admin, then it's not recommended to use session cookies to authenticate the merchant to your app's server. Instead, use session token authentication to obtain a JWT (JSON web token) from Shopify App Bridge.

After you obtain the JWT, you can use it to look up session data. Using this approach, your app needs to perform an OAuth redirect only for the initial installation, and doesn't need to store the merchant information in a cookie.

1. Generate API credentials

The first step is to retrieve an API key and API secret key. These API credentials identify your app during the authorization process.

1. Log in to your Partner Dashboard.
2. Click Apps.
3. Choose the type of app that you want to create.
4. Click Create app.
5. Enter the app name, app URL, and allowed redirection URLs for your app.
6. Click Create App.
7. Scroll to API Keys to view your API key and API secret key.

2. Generate an installation link

If you're authenticating a public app, then skip this step and proceed to step 3.

If you're authenticating a custom app, then you need to generate an installation link. A custom app can interact with the Shopify API on behalf of a single store. The merchant uses the link to go through the OAuth process and install the app on their store.

1. From the app's page in your Partner Dashboard, click Generate link.
2. Enter the merchant's myshopify.com domain name. For example, mygreatstore.myshopify.com.
3. Click Generate link, and then click Generate link to confirm.
4. Copy the installation link from the Merchant install link section and proceed to step 3.

Install a custom app on multiple stores

Usually, a custom app can be installed only on one store. However, Shopify Plus service partners can install a custom app on multiple Shopify Plus stores owned by a single Shopify Plus merchant.

1. From the app's page in your Partner Dashboard, click App setup.

2. In the Shopify Plus section, click Request access.

   After the next step, your app will be restricted to Shopify Plus stores, and can be installed only on the stores of a single Shopify Plus merchant.

3. Click Request access again to confirm.

4. Copy the installation link from the Plus merchant install link section and proceed to step 3.

3. Ask for permission

Before an app can access any store data, a merchant must grant permission to the app. Granting permission happens when a merchant clicks the link to install your app.

How the installation flow works

After a merchant clicks the link to install your app, your app receives a GET request on the app URL path that you specified in the Partner Dashboard. Requests to this URL path from a merchant who is logged into the Shopify App Store include the shop, timestamp, and hmac query parameters.

If your install link doesn’t originate from the Shopify App Store, then you need to provide the shop parameter yourself or use another method to get the merchant's shop.

You need to verify the authenticity of these requests using the provided HMAC. For more information, refer to Verification.

Installation permissions prompt

Shopify shows the following prompt to receive authorization from the merchant.

Show the installation permissions prompt

To show the prompt, redirect the merchant to the following URL with the query parameters defined below:

Orders permissions

By default, you have access to the last 60 days' worth of orders for a store. To access all the orders, you need to request access to the read_all_orders scope from the merchant:

1. From the app's page in your Partner Dashboard, click App setup.
2. In the Orders section, click Request access to all orders.
3. Provide a description about why you are applying for access.

4. Click Request access.

   If the merchant approves your request, then you can add the read_all_orders scope to your app along with read_orders or write_orders.

Subscription APIs permissions

Subscription apps let merchants sell subscription products that generate multiple orders on a specific billing frequency.

With subscription products, the merchant isn't required to get customer approval for each subsequent order after the initial subscription purchase. As a result, your app needs to request the required protected access scopes to use Subscription APIs from the merchant:

1. From the app's page in your Partner Dashboard, click App setup.
2. In the Subscriptions section, click Request access to Subscription APIs.
3. Provide a description about why you are applying for access.
4. Click Request access.

If the merchant approves your request, then you can add the read_customer_payment_methods and write_own_subscription_contracts scopes to your app.

4. Confirm installation

When the merchant clicks the install button in the prompt, they’re redirected to your app's server. The authorization_code is passed in the confirmation redirect:

Security checks

Before you continue, make sure that your app performs the following security checks. If any of the checks fail, then your app must reject the request with an error, and must not continue.

• The nonce is the same one that your app provided to Shopify during step three.
• The hmac is valid and signed by Shopify.

• The shop parameter is a valid shop hostname, ends with myshopify.com, and doesn't contain characters other than letters (a-z), numbers (0-9), periods, and hyphens.

  You can use a regular expression to confirm that the hostname is valid. In the following example, the regular expression matches the hostname form of https://exampleshop.myshopify.com/:

  To match for the hostname form exampleshop.myshopify.com, you can use the following regular expression:

Embedded apps

For security purposes, embedded apps are required to lock all communications to the shop_origin.

Shop origin

The shop origin is the hostname for the current shop, which consists of the shop name followed by myshopify.com. The shop origin for the current session is contained in the host URL query parameter that’s appended to your application URL when your app is loaded inside the Shopify admin.

The host parameter is an encoded version of the shop origin that is required for Shopify App Bridge version 2.0. If you're using Shopify App Bridge version 1.0, use the shop parameter instead.

Several Shopify-provided libraries require the shop origin, including Shopify App Bridge, Polaris, and the Embedded App SDK. It’s a good idea to retrieve it and then store it for the duration of the session.

Get and store the shop origin using the shopify_app gem

If you’re using the shopify_app gem, then the host parameter is automatically parsed from the authentication URL and stored in the session under the :shopify_domain key. For example, session[:shopify_domain].

Get and store the shop origin manually

If you’re unable to use any of the Shopify-provided libraries, then you need to parse the host parameter out of the authentication URL and store it for later use.

To get the host parameter, parse it out of the confirmation redirect URL during the installation confirmation step of the authorization process.

After you’ve got the host parameter, you need to store it for the duration of the user session. It’s best to use the session mechanism of your preferred framework. Otherwise, you can store the parameter in an HTTP-only cookie.

Get a permanent access token

If all security checks pass, then you can exchange the access code for a permanent access token by sending a request to the shop’s access_token endpoint:

In your request, {shop} is the name of the merchant's shop and the following parameters must be provided in the request body:

The server responds with an access token:

The following values are returned:

Changing requested scopes

Due to the nature of OAuth, it’s possible for a merchant to change the requested scope in the URL during the authorize phase, so the app should ensure that all required scopes are granted before using the access token.

If you requested both the read and write access scopes for a resource, then check only for the write access scope. The read access scope is omitted because it’s implied by the write access scope. For example, if your request included scope=read_orders,write_orders, then check only for the write_orders scope.

Online access mode

If online access mode is requested, then the server responds with an access token and additional data:

The following values are returned:

5. Make authenticated requests

After your app has obtained an API access token, it can make authenticated requests to the Admin API. These requests are accompanied with a header X-Shopify-Access-Token: {access_token} where {access_token} is replaced with the permanent token.

The following examples show how to retrieve a list of products using the GraphQL Admin API and the REST Admin API.

Changes to granted scopes

After the merchant has agreed to install your app, you might want to change the granted scopes. For example, you might want to request additional scopes if your integration requires access to other API endpoints.

To change scopes, redirect the merchant to the app authorization link and request authorization of new permissions:

In the URL, {shop} is the name of the merchant's shop and the oauth/authorize link includes the required parameters.

Verification

Every request or redirect from Shopify to your app's server includes an hmac parameter that can be used to verify the authenticity of the request from Shopify. For each request, you must remove the hmac entry from the query string and process it through an HMAC-SHA256 hash function.

The following is an example of a query string. However, request parameters provided by Shopify are subject to change. Your verification strategy shouldn't depend on the parameters in the following example:

IDs array parameter

If your query string includes an ids array parameter, then the query string is parsed so that ids[]=1&ids[]=2 gets converted to ids=["1", "2"] before the signature is generated.

Remove the HMAC

To remove the hmac, you can transform the query string to a map, remove the hmac key-value pair, and then lexicographically concatenate your map back to a query string. This leaves the remaining parameters from the example query string:

Process through the hash function

You can process the string through an HMAC-SHA256 hash function using the secret key. The message is authentic if the generated hexdigest is equal to the value of the hmac parameter.

The following Ruby example shows how to process the string through a hash function:

Next steps

• Authenticate your embedded app using session tokens.
• Learn how to configure a webhook for your app and manage webhooks for different API versions.
• Explore the GraphQL Admin API and REST Admin API references.