Shopify API Authentication

Shopify implements OAuth2 as the primary mechanism for authenticating against our API. For a detailed technical explanation of the spec, see here.

If you’re still using our old HTTP basic auth authentication method, you can find the relevant docs here.

Basics

Every Shopify app is issued an api key and a shared secret. These are shown on your app’s page in the Partners dashboard. The secret should be kept secret: If a third party gets access to it they’ll be able to impersonate you and get access to any shop that has your app installed.

There are several steps that an app must complete in sequence to authenticate against a shop, at the end of which a token is generated that allows the app to make calls to the API on behalf of the merchant.

Step 1

To initiate authentication, redirect the merchant to the following URL:


  GET https://SHOP_NAME.myshopify.com/admin/oauth/authorize

with the following parameters:

client_id – Required – The API key for your app
scope – Required – The list of required scopes (explained below)
redirect_uri – Optional – The URL that the merchant will be sent to once authentication is complete. Must be the same host as the Return URL specified in the application settings

Once here, the merchant will be asked to grant the requested permissions.

Assuming the user grants access, Shopify redirects to the redirect_uri specified by the app with a temporary access token code as a parameter. Given the redirect URL

http://shopify.com/app

the call will look like this:

GET http://shopify.com/app?code=TEMP_TOKEN

Step 2

Exchange the temporary token for a permanent access token using the following request:

POST https://SHOP_NAME.myshopify.com/admin/oauth/access_token

with the following parameters:

client_id – Required – The API key for your app
client_secret – Required – The shared secret for your app
code – Required – The token you received in step 1

The response will contain your access token.

Step 3

Use the token to access the API. To do this, set a ‘X-Shopify-Access-Token’ header on all your requests that contains the access token. The token is good for the lifetime of the install, so save it somewhere secure for use later on. You can also append the token as a URL parameter, but the header version is preferred.

Scopes

Through OAuth2 you can request various access scopes for your app. For example, an app that only deals with orders can just request the order scope and not gain access to extra info like products, themes, or blogs. The scopes are listed below followed by the endpoints they give access to. Note that write permission implies reading, so you don’t need to request both.

(read|write)_content

(read|write)_themes

Asset
Theme

(read|write)_products

(read|write)_customers

(read|write)_orders

(read|write)script_tags

ScriptTag

(read|write)_shipping

Shipping (Coming Soon)

All apps get access to the following resources by default:

Other Scopes

Some scopes are implied. Both Metafields and Webhooks rely on other objects, so permissions for these are granted alongside the resources they operate on. This means that if you request the Order scope, you’ll get access to order webhooks and be able to read/write metafields on orders.

Examples

Requesting access to a shop with write access to products and read access to orders:

https://SHOP_NAME.myshopify.com/admin/oauth/authorize?client_id=API_KEY&scope=write_products,read_orders

Requesting access to a shop with no additional permissions beyond the basics:

https://SHOP_NAME.myshopify.com/admin/oauth/authorize?client_id=API_KEY

Requesting access to a shop with product write permissions and a custom redirect URL. Notice that the URL is encoded:

https://SHOP_NAME.myshopify.com/admin/oauth/authorize?client_id=API_KEY&scope=write_products&redirect_uri=http%3A%2F%2Fshopify.com%2Fapp%2Flogin

Migration from legacy auth

Existing apps using the legacy auth do not have to re-authorize existing shops when they switch to OAuth2. The password previously used to authenticate can be reused as the auth token seen in Step 3 above. Where an app would previously use basic auth like this:

https://api-key:password@some-shop.myshopify.com/admin/orders.xml

Then setting the X-Shopify-Access-Token header to password instead would allow the app to authenticate as normal.

Note: Make sure you use your app's password and not the token that Shopify provides post authentication. Refer to the legacy auth docs for details on how to generate passwords from tokens.

App Store Installs

If your app is installed from the Shopify App Store then the merchant will be redirected to your default app URL as defined in the Partners dashboard. You will then have to start the auth process as described above.

To help you get started the shop URL will be appended as a parameter on this request. We also sign these requests in a similar fashion to our webhooks, see here for more details on this.

Given the redirect URL