Scopes

API keys should use the smallest set of scopes required by the integration. Scopes are enforced by endpoint family.

Scope Families

Scope	Allows
products:read	List/read products and product compositions.
products:write	Create/update products and replace product compositions.
inventory:read	Read locations, owners, channels, balances, movements, lots, serials, inbounds and outbounds.
inventory:write	Create/update locations, owners, channels, stock operations, inbounds and outbounds.
reservations:read	List/read reservations.
reservations:write	Create, commit, release and cancel reservations.
transfers:read	List/read transfers.
transfers:write	Create, ship, receive, close and cancel transfers.
reports:read	Read inventory snapshot, stock movement, operations summary and exception reports.
reports:export	Create, list, inspect, delete and download report exports.

Endpoint Mapping

Endpoint family	Read scope	Write scope
/products	products:read	products:write
/products/{productId}/composition	products:read	products:write
/locations	inventory:read	inventory:write
/inventory-owners	inventory:read	inventory:write
/inventory-channels	inventory:read	inventory:write
/balances	inventory:read	Not writable directly.
/movements	inventory:read	Not writable directly.
/lots, /lot-balances, /serials	inventory:read	Mutated through stock and workflow operations.
/stock/*	Not applicable.	inventory:write
/reservations	reservations:read	reservations:write
/transfers	transfers:read	transfers:write
/inbounds	inventory:read	inventory:write
/outbounds	inventory:read	inventory:write
/reports/*	reports:read	Not writable directly.
/report-exports	reports:export	reports:export

Least-Privilege Examples

A reporting integration that only reads balances and movements usually needs:

inventory:read

A reporting integration that reads reports and downloads CSV/XLSX exports needs:

reports:read
reports:export

Scopes grant endpoint access; report plan capabilities and quotas are enforced separately and can return PLAN_LIMIT_EXCEEDED.

A catalog sync that manages products but does not move stock needs:

products:read
products:write

A warehouse integration that receives stock, creates inbounds and reads balances needs:

inventory:read
inventory:write

An order allocation service that creates reservations and later commits or cancels them needs:

inventory:read
reservations:read
reservations:write

Missing Scopes

Missing scopes return a structured FORBIDDEN error. Keep the response requestId in logs so the failed request can be investigated.