All Tutorials

Authenticate a private app with the Shopify admin

All Tutorials

Authenticate a private app with the Shopify admin

Authenticate a private app with the Shopify admin

A private Shopify app can interact with the Shopify API on behalf of a single store. 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.

Enable private app development

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

Generate credentials from the Shopify admin

Before you can authenticate a private app to Shopify, you need to generate the required credentials from the Shopify admin of the store that you want to connect with your app. If you don't have a Shopify store, then you can log in to your Partner dashboard and click Development stores to create a test store.

After you've provisioned a test store, log in and then generate the required credentials from the test store admin:

  1. From your Shopify admin, go to Apps.

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

  3. Click Create a new private app.

  4. In the App details section, enter a name for the private app and a contact email address. Shopify uses the 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. If you want to use the Storefront API, then select Allow this app to access your storefront data using the Storefront API.

  7. In the Storefront API permissions section, select which types of data you want to expose to the app.

    Four permissions are selected by default:

    • Read products, variants, and collections
    • Read and modify customer data
    • Read and modify checkouts
    • Read content like articles, blogs, and comments
  8. Click Save.

You'll see your API key and password in the Admin API section. You can use these credentials to make authenticated requests to the Shopify store that uses your application.

If you allowed the app to access your storefront data, then you'll see a storefront access token in the Storefront API section.

Change permissions for a storefront access token

After you've created a storefront access token, you can change its permissions to limit what areas of a store can be accessed by the private app.

Anyone with a staff account or a collaborator account and the required permissions can change the token's permissions. For more information, refer to Changing private app permissions as a staff member or collaborator

Steps:

  1. From your Shopify admin, go to Apps.

  2. Click Manage private apps.

  3. Click the name of the app whose permissions you want to change.

  4. In the Storefront API section, under Storefront API permissions, select which areas of the store you want the app to access.

    Four permissions are selected by default:

    • Read products, variants, and collections
    • Read and modify customer data
    • Read and modify checkouts
    • Read content like articles, blogs, and comments
  5. Click Save.

  6. In the You've made changes to your app dialog, click Save.

Changing private app permissions as a staff member or collaborator

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 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 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
write_kit_skills None (except for Edit private app details and permissions)
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

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. You can generate these credentials from the Shopify admin of the store that you want to connect with your app.

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

GET https://{username}:{password}@{shop}.myshopify.com/admin/api/2021-04/shop.json

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:

    Authorization: Basic NDQ3OGViN2FjMTM4YTEzNjg1MmJhYmQ4NjE5NTZjMTk6M2U1YTZlZGVjNzFlYWIwMzk0MjJjNjQ0NGQwMjY1OWQ=

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.