Permissions

Permissions are a vocabulary of scopes, each a resource:action pair. You declare what your app needs; the merchant approves it at install; we enforce it on every request. Your code never checks a permission — a call either succeeds or answers 403 with the missing scope named.

Declaring them

{
  "scopes": ["transactions:read", "products:read", "inventory:write", "emails:send"],
  "optional_scopes": ["emails:send"]
}

scopes is everything the app can use. optional_scopes is the subset the merchant may decline at install; the app must work without them. Ask for the narrowest set that works — a consent screen listing eighteen permissions is one merchants abandon — and request an optional scope at the moment you need it with paysio.requestScope().

The vocabulary

Every scope an app can declare today, with the tier the merchant sees it under.

Unknown scopes are rejected when you save the config. Scopes for features not yet exposed to apps (campaigns, storefront publishing, checkout settings, risk settings and others) exist in the platform but cannot be declared until they open; they will appear here when they do.

Tiers

• Standard — non-personal reads and content writes. Listed plainly at install.
• Sensitive — personal data, or acting as the merchant (sending email). Listed with a note.
• Money — anything that moves or promises money: charges, refunds, invoices, subscriptions. Open to every app. Called out with its own warning at install, where the merchant must also tick that they understand the app can move money before Install enables, and again on the app’s page. Every charge an app makes shows in Transactions.

Some capabilities are absent from the vocabulary by construction and can never be granted to an app: API keys, members and roles, security settings, processor credentials, billing. There is no scope to ask for, which is what makes them safe.

How enforcement works

Every /v1 request resolves the intersection of three sets — what your app declares, what this merchant granted, and what the token carries — recomputed per request, so a revoked scope stops working on the very next call. A path with no scope rule is denied, never allowed, so a new endpoint can never quietly become reachable to apps.

HTTP/1.1 403 Forbidden
{
  "error": "This app has not been granted the required permission: emails:send. The merchant can grant it from the app's page.",
  "scope": "emails:send",
  "type": "invalid_request_error"
}

Webhooks are gated the same way: a topic is only delivered to apps granted the read scope its payload implies. See Storage & webhooks.

Requesting more later

Changing what you need

Merchants can also revoke individual scopes from your app’s page at any time. Design for a call to fail with 403 and say what to do, rather than assuming what was granted yesterday is granted today.