Skip to main content

Scopes and Permissions

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 generally structured as resource:action. Common actions include read and write.

Content​

ScopeDescription
content:readRead access to site pages, blocks, and content.
content:writeWrite access to site pages and content.

Media​

ScopeDescription
media:readView and list media files in the library.
media:writeUpload and manage media files.

Leads​

ScopeDescription
leads:readRead form submissions and lead data.
leads:writeCreate or update lead information.

Payments​

ScopeDescription
payments:readView transaction history and payment status.
payments:writeInitiate or manage payments (where applicable).

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: The merchant is shown the list of requested scopes during install.
  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​