Skip to content

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).

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).

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.