Authorization (RBAC & scopes)
Authentication proves who you are. Authorization limits what you can do.
Staff RBAC (Merchant BO)
| Role | Typical powers |
|---|
| Owner | Full control including billing, delete shop, transfer ownership |
| Admin | Commerce + staff + integrations; no ownership transfer |
| Developer | API keys, webhooks, sandbox tools; limited billing |
| Integration Manager | API keys/webhooks/connectors; no staff invite |
| Read Only | View catalog/orders/customers; no writes |
API keys inherit the intersection of: (1) creator’s role ceiling, (2) explicitly granted scopes. A Read Only user cannot mint orders.write keys.
API key scopes
(OAuth partner apps are in development; the same scope strings will apply when OAuth ships.)
Scopes are dotted resource.action strings.
Catalog
| Scope | Allows |
|---|
products.read | List/get products, variants, categories |
products.write | Create/update/delete products & variants |
categories.read | Category tree read |
categories.write | Category mutations |
Orders & fulfillment
| Scope | Allows |
|---|
orders.read | List/get orders, timelines (PII per policy) |
orders.write | Status updates, notes, cancel (policy-bound) |
fulfillments.write | Create shipments / fulfill |
returns.write | Initiate/process returns |
Customers
| Scope | Allows |
|---|
customers.read | Customer profiles (masked fields may apply) |
customers.write | Update customer attributes where allowed |
Inventory & pricing
| Scope | Allows |
|---|
inventory.read | Stock levels / locations |
inventory.write | Adjust stock |
prices.write | Price list updates |
Platform integration
| Scope | Allows |
|---|
webhooks.manage | CRUD webhook endpoints |
media.write | Upload media metadata / URLs |
analytics.read | Aggregate metrics (no raw PII dumps) |
Meta
| Scope | Allows |
|---|
* | All scopes — Owner only; discouraged for automations |
Permission evaluation order
- Tenant active? (suspended →
403 TENANT_SUSPENDED)
- Credential valid?
- Scope present for route?
- Resource belongs to credential’s tenant?
- Plan quota / feature flag?
Failures return structured errors — see Error handling.
Least privilege examples
| Integration | Suggested scopes |
|---|
| Read-only BI export | orders.read products.read customers.read |
| WMS stock sync | inventory.read inventory.write orders.read fulfillments.write |
| Marketing ESP sync | customers.read (+ webhook customer.*) |
| n8n order → ERP | orders.read + webhook order.* (prefer push) |