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
Anchor link to section titled "Requirements"- You've created a development store.
- You understand how apps fit into Shopify and the different ways that you can distribute your app.
- You're familiar with the different methods of authenticating and authorizing apps with Shopify’s platform.
How basic HTTP authentication works
Anchor link to section titled "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.
- The app requests access to a Shopify API resource.
- Shopify requests a username and password to authenticate the request.
- The app sends the username and password to Shopify.
- Shopify returns the requested data.
Limitations and considerations
Anchor link to section titled "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 401
error code. Using cookies with basic authentication can expose your app to CSRF attacks, such as session hijacking.
Step 1: Enable private app development
Anchor link to section titled "Step 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.
Step 2: Generate API credentials
Anchor link to section titled "Step 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.
From your Shopify admin, go to Apps.
Click Manage private apps, near the bottom of the page.
Click Create new private app.
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.
In the Admin API section, select the areas of your store that you want the app to be able to access.
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.
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.
Step 3: Make authenticated requests
Anchor link to section titled "Step 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
Anchor link to section titled "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:
Join the API key and password with a single colon (
:
).Encode the resulting string in base64 representation.
Prepend the base64-encoded string with
Basic
and a space:
Shopify access token
Anchor link to section titled "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.
Changing API scopes
Anchor link to section titled "Changing API scopes"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
Anchor link to section titled "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 |
View store metrics |
read_assigned_fulfillment_orders , write_assigned_fulfillment_orders |
View or manage fulfillment orders |
read_customers , write_customers |
View or manage customers, customer addresses, order history, and customer groups |
read_discounts , write_discounts |
View or manage automatic discounts and discount codes |
read_draft_orders , write_draft_orders |
View or manage orders created by merchants on behalf of customers |
read_files , write_files |
View or manage files |
read_fulfillments , write_fulfillments |
View or manage fulfillment services |
read_gdpr_data_request |
View GDPR data requests |
read_gift_cards , write_gift_cards |
View or manage gift cards (Available to Plus merchants only) |
read_inventory , write_inventory |
View or manage inventory across multiple locations |
read_legal_policies , write_legal_policies |
View or manage a shop’s legal policies |
read_locations |
View the geographic location of stores, headquarters, and warehouses |
read_marketing_events , write_marketing_events |
View or manage marketing events and engagement data |
read_merchant_managed_fulfillment_orders , write_merchant_managed_fulfillment_orders |
View or manage fulfilment orders assigned to merchant-managed locations |
read_online_store_navigation |
View menus for display on the storefront |
read_online_store_pages , write_online_store_pages |
View or manage Online Store pages |
read_order_edits , write_order_edits |
View or manage edits to orders |
read_orders , write_orders , read_all_orders |
View or manage orders, transactions, fulfillments, and abandoned checkouts from the last 60 days, or View all past and future orders |
read_price_rules , write_price_rules |
View or manage conditional discounts |
read_products , write_products |
View or manage products, variants, and collections |
read_product_listings , write_product_listings |
View or manage product or collection listings |
read_reports , write_reports |
View or manage reports on the Reports page in the Shopify admin |
read_resource_feedbacks , write_resource_feedbacks |
View or manage the status of shops and resources |
read_script_tags , write_script_tags |
View or manage the JavaScript code in storefront or orders status pages |
read_shipping , write_shipping |
View or manage shipping carriers, countries, and provinces |
read_shopify_payments_accounts |
View Shopify Payments accounts |
read_shopify_payments_bank_accounts |
View bank accounts that can receive Shopify Payment payouts |
read_shopify_payments_disputes |
View Shopify Payment disputes raised by buyers |
read_shopify_payments_payouts |
View Shopify Payments payouts and the account’s current balance |
read_content , write_content |
View or manage articles, blogs, comments, pages, and redirects |
read_themes , write_themes |
View or manage theme templates and assets |
read_third_party_fulfillment_orders , write_third_party_fulfillment_orders |
View or manage fulfillment orders assigned to a location managed by any fulfillment service |
read_translations , write_translations |
View or manage content that can be translated |
- 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.