Scopes define which API resources and operations a key is permitted to access. Each scope follows the pattern resource:action.
Available Scopes #
| Scope | Permitted Operations |
|---|---|
customers:read | List and retrieve customer records |
customers:write | Create and update customer records |
customers:delete | Soft-delete customer records |
products:read | List and retrieve product records |
products:write | Create and update product records |
products:delete | Deactivate product records |
licenses:read | List and retrieve license records |
licenses:write | Create and update license records |
licenses:delete | Revoke license records |
activations:read | List and retrieve activation records |
activations:write | Activate and deactivate licenses |
subscriptions:read | List and retrieve subscription records |
subscriptions:write | Create, update, renew, cancel, and reactivate subscriptions |
subscriptions:delete | Delete subscription records |
downloads:read | Generate and consume download tokens; view download history |
downloads:write | Create download tokens and trigger file delivery |
activations:delete | Remove activation records |
versions:read | List and retrieve product version records |
versions:write | Create, update, and upload files for product versions |
versions:delete | Delete product version records |
admin | Grants all permissions including administrative endpoints (e.g., /admin/metrics) |
Scope Templates #
Templates provide a convenient starting point when creating a key:
| Template | Scopes Granted | Use Case |
|---|---|---|
read-only | All :read scopes (7 scopes) | Reporting integrations, dashboards, read-only sync services |
full-access | All :read, :write, and :delete scopes (20 scopes) | Full sync services, import/export tools |
admin | ['admin'] — grants all permissions | Internal automation, administrative tooling |
Insufficient Scope Response #
When a request is authenticated but the key does not have the required scope for the requested operation, the API returns:
HTTP 403 Forbidden
{
"code": "insufficient_scope",
"message": "The API key does not have the required scope for this operation.",
"data": { "required_scope": "licenses:write" }
}