Maintain admin-created custom apps
You can no longer create new admin-created custom apps. Management of existing apps is moving to the Dev Dashboard. A moved app works the same and keeps its installation, access token, and access scopes. To create a new app, use the Dev Dashboard or Shopify CLI.
You can no longer create new admin-created custom apps. Management of existing apps is moving to the Dev Dashboard. A moved app works the same and keeps its installation, access token, and access scopes. To create a new app, use the Dev Dashboard or Shopify CLI.
Admin-created custom apps are apps created directly in the Shopify admin. Shopify generates API access tokens when the merchant installs the app. In the Shopify admin, these apps are listed as legacy custom apps.
In the Dev Dashboard, you can manage your app, including viewing logs of its API requests and webhook deliveries and setting up an IP allowlist. Use this page to get your access token, make authenticated requests, generate a new access token, and change access scopes.
Anchor to Get your access tokenGet your access token
Admin-created custom apps authenticate with an Admin API access token. Shopify generated the access token when the app was installed in the store. It doesn't expire, so treat it like a password and keep it secret.
Your access token is on your app's page in the Shopify admin, not in the Dev Dashboard. To get it:
- In the Shopify admin, go to Settings > Apps and sales channels > Develop apps, and then click your app.
- On the Admin API access token card, click Reveal token once. If your app's page has tabs, then the card is in the API credentials tab.
If your app uses the Storefront API, then its Storefront API access token is on the same page.
You can reveal the access token only once, so store it somewhere secure. If you no longer have it, then generate a new one.
Anchor to Make authenticated requestsMake authenticated requests
To make authenticated requests, include your access token in the X-Shopify-Access-Token header. To check that your access token works, send a test request from the command line with cURL.
The following examples query the GraphQL Admin API to retrieve the first five products from a store. For more examples, see Authentication in the GraphQL Admin API reference.
The following examples require the SHOP_TOKEN environment variable set to your Admin API access token with at least the read_products scope. Replace {shop} with your store's subdomain.
The following examples require the SHOP_TOKEN environment variable set to your Admin API access token with at least the read_products scope. Replace {shop} with your store's subdomain.
cURL
You can pipe the response through jq to extract specific fields:
cURL with jq
Anchor to Generate a new access tokenGenerate a new access token
To generate a new access token, uninstall and reinstall the app from the Shopify admin. The app itself stays intact: uninstalling removes it from the store, and reinstalling generates a new access token. Your app's requests and webhooks are disrupted until you update your code with the new access token.
To also rotate your app's client secret, follow Rotate your client secret, and uninstall and reinstall the app after you generate the new secret. Apps that haven't moved to the Dev Dashboard can't rotate their client secret.
Deleting the app in the Dev Dashboard is permanent, and you can't create a new admin-created custom app to replace it. If your app hasn't moved to the Dev Dashboard yet, then deleting it in the Shopify admin is also permanent. If you need a new app, use the Dev Dashboard to create one with a proper OAuth flow.
Deleting the app in the Dev Dashboard is permanent, and you can't create a new admin-created custom app to replace it. If your app hasn't moved to the Dev Dashboard yet, then deleting it in the Shopify admin is also permanent. If you need a new app, use the Dev Dashboard to create one with a proper OAuth flow.
If you need to rotate access tokens for a custom storefront built with the Headless channel, see Rotate private access tokens.
Anchor to Change access scopesChange access scopes
Access scopes control which store data your app can read and change through the GraphQL Admin API and the Storefront API. To change them, you release a new app version with the updated scopes in the Dev Dashboard, and then approve the new scopes on the app's page in the Shopify admin. Your access token stays the same, so you don't need to reinstall the app or update your code.
- On your app's page in the Shopify admin, click Manage scopes on the Manage in Dev Dashboard card.
- In the Dev Dashboard, click Create version, update the scopes, and then click Release.
- Go back to your app's page in the Shopify admin. On the New access requested banner, click Review access, and then click Update.
After you click Update, the app can use the new scopes.
Keep the following in mind when you change scopes:
- Approving grants only the scopes that the version requires, not optional ones.
- If the app isn't installed, then the New access requested banner doesn't appear. Installing the app grants the scopes of its current version.
- If the new version only removes scopes, then the banner doesn't appear, and the app keeps its current access. To apply the version, uninstall and reinstall the app from the Shopify admin. Reinstalling generates a new access token, so update your code with it.
- A version that removes every Admin API access scope, or every Storefront API access scope, that the store granted can't be approved. Release a version that keeps at least one scope of that API, or uninstall the app if you no longer need it.
If your app hasn't moved to the Dev Dashboard yet, then change its scopes in the Configuration tab on the app's page in the Shopify admin.
Anchor to Permissions required to approve scopesPermissions required to approve scopes
To approve new access scopes in the Shopify admin, a staff member or collaborator needs the Manage and install apps and channels permission, the Develop apps permission, and the store permissions for each scope that the app requests. Without them, the New access requested banner asks you to get permission from the store owner.
To release a version with new scopes, you need access to the Dev Dashboard in the store's organization. Collaborators can open the app in the Shopify admin, but not in the Dev Dashboard, so they can't change its access scopes.
The following table shows what store permissions a staff member or collaborator needs to approve each Admin API access scope. They must also have the Develop apps permission in all cases.
| Admin API scope name | Permissions required |
|---|---|
read_analytics | View store metrics |
read_assigned_fulfillment_orders, write_assigned_fulfillment_orders | View or manage fulfillment orders |
read_customer_merge, write_customer_merge | View or manage customer profile merges |
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 app users 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 (Shopify Plus 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 fulfillment orders assigned to merchant-managed locations |
read_metaobject_definitions, write_metaobject_definitions | View or manage metaobject definitions |
read_metaobjects, write_metaobjects | View or manage metaobject entries |
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 JavaScript code in storefront or order 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 Payments payouts |
read_shopify_payments_disputes | View Shopify Payments 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 |
Anchor to Next stepsNext steps
- Learn how to configure a webhook for your app and manage webhooks for different API versions.
- Explore the Webhooks references and GraphQL Admin API references.
- In the Dev Dashboard, view your app's logs and set up an IP allowlist.