Scopes
A scope grants access to one resource and one action. An app declares the scopes it asks for on its Details tab; the organization's approver grants them when installing it (a public app on the consent screen, a private app on its install link's page).
v1 scopes
Section titled "v1 scopes"| Scope | Allows |
|---|---|
read_orders |
Reading orders: GET /orders, GET /orders/{id}. order.* webhooks. |
read_shipments |
Reading shipments (AWB): GET /shipments, GET /shipments/{id}. shipment.* webhooks. |
write_shipments |
Creating a shipment for an order (POST /shipments) and cancelling it (POST /shipments/{id}/cancel). |
read_invoices |
Reading invoices: GET /invoices, GET /invoices/{id}. invoice.* webhooks. |
write_invoices |
Issuing an invoice for an order: POST /invoices. |
read_integrations |
The organization's integrations: GET /integrations, GET /integrations/{id}. |
write_orders |
A store app sending its orders, created or updated by its own id (POST /orders, POST /orders/batch) (store apps). Asked only beside what the app provides with it. Reading them back needs read_orders. |
Scopes are lowercase, with _. In an OAuth request, the scope parameter separates them with spaces: scope=read_orders read_shipments.
The ceiling: the approver's permissions
Section titled "The ceiling: the approver's permissions"Access never exceeds what the person approving the app may do, at the moment they approve it. Every scope sits on a permission in the dashboard:
| Scope | Permission required in the approver's role |
|---|---|
read_orders |
view orders |
read_shipments |
view shipments |
write_shipments |
manage shipments |
read_invoices |
view invoices |
write_invoices |
manage invoices |
read_integrations |
view integrations |
write_orders |
manage integrations |
The approver also needs the permission to manage the organization's connected apps, and must hold the permission behind every scope the app asks for. Where one is missing, the approval is refused, with the reason shown.
Once granted, access belongs to the organization: the approver's role is not read again on each request, and access survives the person leaving. It ends only when the installation ends (the app uninstalled, retired or deleted); a suspension pauses it.
Scopes carried by what the app provides
Section titled "Scopes carried by what the app provides"Some scopes exist for an integration an app provides (what the app provides), such as write_orders for a store sending its orders. Such a scope is asked only together with that capability: saving a version that asks for it without the capability is refused, naming the capability. Installing the app then also asks the approver for the capability's permission (managing integrations, for a store).
Checked on every request
Section titled "Checked on every request"Every endpoint requires its scope. A request without it is refused with an application/problem+json error (errors), without touching any data. One endpoint needs none: GET /organization answers any valid token with its organization and the scopes it holds (caller.scopes). An app reads there what each installation granted it (OAuth). A private app's token may be narrowed further when it is asked for (client credentials).
Ask only for the scopes you need: the approver sees all of them.