Basic HTTP authentication

Private apps authenticate using basic HTTP authentication in order to use Shopify’s API resources. This guide shows you how to authenticate a private app.

Requirements

• You've created 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.

How basic HTTP authentication works

To authenticate with Shopify by using a private app, you need to generate the credentials from the Shopify admin and provide these credentials in your request to Shopify.

1. The app requests access to a Shopify API resource.
2. Shopify requests a username and password to authenticate the request.
3. The app sends the username and password to Shopify.
4. Shopify returns the requested data.

Limitations and considerations

Shopify doesn't support cookies in POST requests that use basic HTTP authentication. Any POST requests that use basic authentication and include cookies will fail with a 200 error code. Using cookies with basic authentication can expose your app to CSRF attacks, such as session hijacking.

1. Enable private app development

Before you can create a private app for a store, the store owner must enable private app development on their store. Contact the store owner and make sure that they've enabled this setting first.

2. Generate API credentials

After the store owner has enabled private app development, you can generate the required credentials from the Shopify admin of the store that you want to connect with your app. These API credentials identify your app during the authorization process.

1. From your Shopify admin, go to Apps.

2. Click Manage private apps, near the bottom of the page.

3. Click Create new private app.

4. In the App details section, enter a name for the private app and a contact email address. Shopify uses this email address to contact the developer if there is an issue with the private app, such as when an API change might break it.

5. In the Admin API section, select the areas of your store that you want the app to be able to access.

6. Optional: To use the Storefront API, select Allow this app to access your storefront data using the Storefront API, and then select which types of data you want to expose to the app.

7. Click Save.

After you save the app's details, the Admin API section shows the app's API key and password. You use these credentials in the next step to make authenticated requests.

3. Make authenticated requests

A private app can make authenticated requests to the REST Admin API or the GraphQL Admin API using basic authentication, or by including its Shopify access token in the request header.

Basic authentication

Private apps can authenticate through basic HTTP authentication by using their Admin API key and password as a username and password.

Some HTTP clients support basic authentication by prepending username:password@ to the hostname in the URL. For example:

• {username}: The API key that you generated.
• {password} : The API password that you generated.
• {shop}: The name of your development store.
• {api-version} — The supported API version that you want to use.
• {resource} - A resource endpoint from the REST Admin API.

A URL with real values looks like this:

If your HTTP client doesn't support basic authentication using this method, then you can provide the credentials in the Authorization header field instead:

1. Join the API key and password with a single colon (:).

2. Encode the resulting string in base64 representation.

3. Prepend the base64-encoded string with Basic and a space:

Shopify access token

Private apps can authenticate with Shopify by including the request header X-Shopify-Access-Token: {access_token}, where {access_token} is replaced by your private app's Admin API password.

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

Changes to permissions

Anyone with a staff account or a collaborator account on a store can change what areas of the store a private app can access, but only if they have all the following permissions:

• the Edit private app details and permissions permission
• the relevant permissions for the area of the store

For example, if the staff or collaborator account has the Orders permissions for the store, then they can change only private permissions related to the store's orders.

The store owner can change the permissions for a staff or collaborator account in the Shopify admin.

Permissions required to assign scopes to a private app

The following table shows what store permissions a staff account or collaborator account needs to assign Admin API access scopes to a private app. In all cases, the account must also have the Edit private app details and permissions permission.

Next steps

• 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.