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

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.

Flowchart of the basic HTTP authentication credential granting process

  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.

Admin API scope name Permissions required for the staff or collaborator account
read_analytics Reports
read_assigned_fulfillment_orders, write_assigned_fulfillment_orders Orders
read_content, write_content Marketing or Pages
read_customers, write_customers Customers
read_discounts, write_discounts Marketing
read_draft_orders, write_draft_orders Draft orders
read_fulfillments, write_fulfillments Orders
read_gdpr_data_request Customers
read_gift_cards, write_gift_cards Gift cards
read_inventory, write_inventory Products
read_legal_policies, write_legal_policies Preferences
read_locales, write_locales Preferences
read_locations Locations
read_marketing_events, write_marketing_events Marketing
read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders Orders
read_online_store_pages, write_online_store_pages Blog posts and pages
read_order_edits, write_order_edits Orders
read_orders, write_orders Orders
read_price_rules, write_price_rules Marketing
read_products, write_products Products
read_product_listings, write_product_listings None (except for Edit private app details and permissions)
read_reports, write_reports Reports
read_resource_feedbacks, write_resource_feedbacks None (except for Edit private app details and permissions)
read_script_tags, write_script_tags Preferences
read_shipping, write_shipping Orders and Preferences
read_shopify_payments_accounts Preferences or View Shopify Payments account details
read_shopify_payments_bank_accounts Preferences or View Shopify Payments account details
read_shopify_payments_disputes None (except for Edit private app details and permissions)
read_shopify_payments_payouts None (except for Edit private app details and permissions)
read_themes, write_themes Themes
read_third_party_fulfillment_orders, write_third_party_fulfillment_orders Orders
read_translations, write_translations Preferences

Next steps