Permissions and scopes
Every API key has a set of scopes that define what it can do. The shape they're stored with isn't a flat list of strings — it's a nested object per resource:
interface ApiKeyScope {
resource: string;
permissions: ApiKeyPermission[];
}
// e.g.: { resource: 'orders', permissions: ['read', 'update'] }This is the shape you select in the creation form (resource × permission checkboxes). Conversion to the resource:action format the rest of the platform uses to authorize (the same one you see in the "Required permission" tables on each endpoint) happens at authentication time for every request, not when you create the key.
Selectable resources
The dashboard lets you choose from these resources when creating a key:
products, orders, customers, channels, inventory, reports, or the * wildcard (everything).
reports is not a resource in the permissions catalog
The dashboard's selector includes reports as an option, but the platform's canonical permissions catalog has no resource named reports — the equivalent resource elsewhere in the system is called insights. If you automate scope creation outside the dashboard, keep this naming mismatch in mind.
This is also a reduced subset: internally the platform recognizes many more resources (returns, integrations, locations, shipping, settings, notifications, categories, billing, CFDI, and more), but only these 6 (+ the wildcard) are available when creating an API key from the dashboard today.
Available permissions
An API key's permission vocabulary is broader than just read/write:
*, read, write, update, delete, create, sync, manage, import, export, fulfill, cancel, configure, connect, disconnect, adjust, transfer, count, track
Doesn't cover every platform action
This vocabulary doesn't map 1:1 to the actions that exist in the internal canonical permissions catalog (for example, actions like approve or process, which do exist elsewhere in the system, have no equivalent on an API key). If your integration needs a very specific action on a resource, verify it's in the list above first.
Conversion to resource:action
When you authenticate a request, each scope is converted into one or more resource:action strings following these rules:
| Input scope | Converts to |
|---|---|
{ resource: '*', permissions: ['*'] } | ['*:*'] |
{ resource: '*', permissions: ['read', 'write', 'delete'] } | ['*:*'] (backwards-compatibility rule — only with exactly those 3 permissions) |
{ resource: 'orders', permissions: ['*'] } | ['orders:*'] |
{ resource: 'orders', permissions: ['read', 'update'] } | ['orders:read', 'orders:update'] (one string per permission) |
How they're evaluated at authorization time
When validating whether an API key can perform an action, the platform checks in this order:
*:*— exact match on the global wildcard.resource:action— exact match.resource:*— resource wildcard.*:action— action wildcard.
A single match at any of these four steps is enough to authorize the request.
Who can define and change scopes
Only whoever can manage API keys can define their scopes — today, only the tenant's owner(s) (see API Key Management). There's no separate screen to edit an existing key's scopes: to change an integration's permissions you have to create a new key with the correct scope and revoke the old one.