Access Scopes

Access scopes control what data and actions your DataJet app can access in your Shopify store. This guide explains how access scopes work and how to manage them.

Overview

Shopify uses OAuth access scopes to control what parts of your store an app can read or modify. DataJet dynamically manages these scopes based on the scripts you create, ensuring your app only requests the permissions it actually needs.

Minimum Required Scopes

DataJet requires the following minimum access scopes to function:

Scope
Description

read_orders

View order information

read_customers

View customer information

read_products

View product information

These scopes are always required and cannot be revoked while the app is installed.

Automatic Scope Detection

DataJet automatically analyzes your scripts to determine which access scopes are required.

How It Works

  1. Code Analysis: When you create or update a script, DataJet parses all GraphQL queries/mutations and REST API calls made to Shopify

  2. Scope Calculation: Based on the API endpoints and operations used, DataJet calculates the required access scopes

  3. Permission Request: If additional scopes are needed, a notification banner appears at the top of your dashboard

Requesting Additional Permissions

When your script requires permissions that haven't been granted yet, a yellow warning banner will appear at the top of the app:

To grant the required permissions:

  1. Review the list of requested scopes displayed in the banner

  2. Click the "Update" button

  3. Shopify will prompt you to authorize the additional permissions

  4. Once approved, the banner will disappear and your script will have the necessary access

Revoking Unused Permissions

When you delete a script or modify it to use fewer API endpoints, some previously granted scopes may no longer be needed. A blue informational banner will appear

To revoke unused permissions:

  1. Review the list of scopes that are no longer needed

  2. Click the "Revoke" button

  3. The unnecessary permissions will be removed from your app

Note: Revoking unused scopes is optional but recommended as a security best practice. It follows the principle of least privilege, ensuring your app only has access to what it currently needs.

Manual Scope Management

While automatic scope detection works for most cases, you may want to manually control which scopes a script requires. This is useful when:

  • You're planning to add API calls that aren't in the code yet

  • You want to pre-authorize scopes before deploying changes

  • The automatic detection doesn't capture dynamically constructed API calls

How to Manually Set Access Scopes

  1. Navigate to Developer Console

  2. Select the script you want to configure

  3. Click on the Cog Wheel icon (settings) next to the script name

  4. Click "Edit" to open the script settings modal

  5. Check the "Manually manage access scopes" checkbox

  6. Select the required scopes from the organized list

Scope Categories

When manually selecting scopes, they are organized into the following categories for easier navigation:

Category
Example Scopes

Products

read_products, write_products, read_product_listings

Orders

read_orders, write_orders, read_draft_orders, write_draft_orders

Customers

read_customers, write_customers

Inventory & Locations

read_inventory, write_inventory, read_locations

Fulfillment & Shipping

read_fulfillments, write_fulfillments, read_shipping

Discounts & Marketing

read_discounts, write_discounts, read_price_rules

Content & Themes

read_content, write_content, read_themes

Metaobjects

read_metaobjects, write_metaobjects

Checkout & Payments

read_checkouts, write_checkouts

Publications & Markets

read_publications, write_publications, read_markets

Read vs Write Scopes

  • Read scopes (e.g., read_products): Allow viewing data only

  • Write scopes (e.g., write_products): Allow creating, updating, and deleting data

Important: When you select a write scope, the corresponding read scope is automatically selected and locked. For example, selecting write_orders will automatically include read_orders since write operations require read access.

Best Practices

Security

  1. Request only what you need: Only enable scopes that your scripts actually use

  2. Revoke unused scopes: When you remove functionality, revoke the associated permissions

  3. Review regularly: Periodically audit your scripts and their required scopes

Development Workflow

  1. Start with automatic detection: Let DataJet analyze your code first

  2. Use manual management for planning: When developing new features, manually add scopes you know you'll need

  3. Test in development: Verify your scripts work with the granted permissions before going live

Troubleshooting

Script Won't Activate

If you can't activate a script, it may require permissions that haven't been granted:

  1. Check for a yellow banner at the top of the dashboard

  2. Grant the required permissions

  3. Try activating the script again

If the permission banner keeps showing after granting access:

  1. Refresh the page

  2. Check if you have multiple scripts requiring different scopes

  3. Ensure all required scopes were approved during the authorization flow

Scope Not Detected Automatically

If DataJet doesn't detect a required scope:

  1. Ensure your API calls use standard GraphQL/REST syntax

  2. For dynamic or constructed API calls, use manual scope management

  3. Check that the API call is within the script code, not in external files

Related Resources

PreviousV2

Last updated