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:
From your Shopify admin, go to Apps.
Click Manage private apps, near the bottom of the page.
Click Create a new private app.
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.
In the Admin API section, select the areas of your store that you want the app to be able to access.
If you want to use the Storefront API, then select Allow this app to access your storefront data using the Storefront API.
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
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:
From your Shopify admin, go to Apps.
Click Manage private apps.
Click the name of the app whose permissions you want to change.
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
Click Save.
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:
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: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.