Scopes and Permissions

Scopes are only needed for an API integration. A storefront app that does not call the API declares no scopes, and merchants install it with one click from the Marketplace.

To protect merchant data, SitePack uses a scope-based permission system. Apps must declare which scopes they require in their app.json manifest. These scopes are then authorized by the merchant during the app installation process.

How Scopes Work

When your app interacts with the SitePack API, it does so within the context of the granted scopes. If your app attempts to access a resource or perform an action that isn't covered by its authorized scopes, the API will return a 403 Forbidden error.

Principle of Least Privilege

You should only request the minimum set of scopes required for your app to function. Requesting unnecessary scopes can decrease merchant trust and may lead to your app being rejected during the review process.

Available Scopes

Scopes are structured as resource:action. write implies its matching read, so an app that holds products:write does not also have to request products:read.

Content

Scope	Description
content:read	Read pages, their elements and revisions.
content:write	Create, change, publish and delete pages.
blogs:read	Read blog posts and blog categories.
blogs:write	Create, change, publish and delete blog posts.
translations:read	Read content translations and site locales.
translations:write	Create and change content translations.
elements:read	Read homepage, footer and sidebar elements.
elements:write	Change homepage, footer and sidebar elements.
navigation:read	Read navigations and their items.
navigation:write	Change navigations and their items.
redirects:read	Read URL redirects.
redirects:write	Create, change and delete URL redirects.
usp:read	Read the site USPs (unique selling points).
usp:write	Create, change, reorder and delete USPs.
comments:read	Read comments.
comments:write	Moderate and delete comments.
posts:read	Read the post types installed apps add to the site, and their entries.
posts:write	Create, change and delete entries of the post types installed apps add, and change the SEO of their overview page.

Media

Scope	Description
media:read	Read the media library.
media:write	Upload, change and delete media.

E-commerce

Scope	Description
products:read	Read products, variants, images and bundles.
products:write	Create, change and delete products and their variants.
inventory:read	Read stock levels and stock locations.
inventory:write	Adjust stock and manage stock locations.
categories:read	Read content and product categories.
categories:write	Create, change and delete categories.
collections:read	Read collections and their rules.
collections:write	Create, change and delete collections.
tags:read	Read tags.
tags:write	Create, change and delete tags.
orders:read	Read webshop orders, their items and payments.
orders:write	Create orders and change their status.
customers:read	Read customers and their addresses.
customers:write	Create and change customers.
discounts:read	Read discount codes.
discounts:write	Create, change and delete discount codes.
shipping:read	Read shipping labels and their track and trace codes.

An orders:read token may read an order but not the customer behind it; reading customer records needs customers:read as well. There is no separate payments scope: an order's payments are read through the order, under orders:read (GET /api/public/v1/orders/{uuid}/payments).

Leads

Scope	Description
leads:read	Read form submissions and their notes.
leads:write	Create, change and delete form submissions.

Site & design

Scope	Description
sites:read	Read the site settings, notices and brand book.
sites:write	Change the site settings, notices and brand book.
modules:read	Read the site modules and their settings.
modules:write	Change module settings.
themes:read	Read the active theme, its layouts and its design settings.
themes:write	Change the theme design settings (colours, fonts) on the staging preview.

Domains & mail

Scope	Description
domains:read	Read domains, DNS records and domain holders.
domains:write	Change DNS records and domain holders.
domains:order	Order domains, which may be charged to the merchant.
mail:read	Read mailboxes and mailbox slots.
mail:write	Create, change and delete mailboxes within the free slots.
mail:order	Create mailboxes beyond the free slots, which is charged monthly.

domains:order and mail:order can cost the merchant money, so the consent screen calls them out separately.

Account & billing

Scope	Description
billing:read	Read the subscription, plan and invoices.
statistics:read	Read site statistics and conversions.

Your app

Scope	Description
app:settings:read	Read this app's own settings on the site, including what the merchant saved on your settings page.
app:settings:write	Change this app's own settings on the site.
webhooks:read	Read this app's webhook subscriptions and the available topics.

The API Reference names the required scope on every endpoint.

Declaring Scopes

Scopes are defined in the auth section of your app.json:

{
  "uuid": "my-app",
  "auth": {
    "scopes": [
      "content:read",
      "media:read",
      "leads:write"
    ]
  }
}

Scoped Security

SitePack enforces these scopes at several levels:

1. OAuth2 Authorization: During install the merchant is shown the requested scopes on the consent screen, grouped by area and described in plain language. Scopes that can spend money (domains:order, mail:order) are called out separately, and only scopes your app declared in its app.json can be granted; a link that asks for more is trimmed to what the manifest allows.
2. API Gateway: Every REST API request is validated against the app's granted scopes.
3. Webhook Delivery: Apps only receive webhooks for resources they have at least read access to.

Next Steps

• Authentication (OAuth): How to obtain tokens with the scopes you've defined.
• App Manifest (app.json): Where to declare your app's scopes.
• Webhooks: Learn how scopes affect webhook data access.
• App Marketplace Policy: How scopes are checked during review.