Scopes & permissions.

Scopes define what an agent key may do. Every agent endpoint checks the request's key for the required scope before executing. If the key lacks the required scope, the API rejects the request with a 403 error.

How scopes work

Each key carries an array of scopes assigned at creation. When a request hits an endpoint:

1. The controller checks which scope(s) the endpoint requires
2. The platform compares the key's scopes against the requirement
3. If any required scope matches, the request proceeds (OR logic)
4. If no scope matches, the platform returns a 403 AUTH_INSUFFICIENT_SCOPE error

Available scopes

Read scope

The read scope is a global read permission. Any key with read can call any GET endpoint.

Write scopes

Write scopes are resource-specific. A key with write:transactions can record purchases but cannot create clubs.

Member write scopes

Member keys use a separate set of write scopes:

Member write scopes are self-scoped. They affect the key owner's data and nothing else.

Super scope

The admin scope bypasses all scope checks. Use it for keys that need unrestricted access.

Admin scopes

Admin keys have platform-level scopes:

Scope hierarchy

Scopes follow a hierarchy:

graph LR
    A["admin"] -->|"grants everything"| B["read"]
    A --> C["write:*"]
    C --> D["write:clubs"]
    C --> E["write:cards"]
    C --> F["write:rewards"]
    C --> G["write:transactions"]
    C --> H["write:stamps"]
    C --> I["write:vouchers"]
    C --> L["write:passes"]
    C --> J["write:tiers"]
    C --> K["write:staff"]

    style A fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e

How the hierarchy behaves:

• Write implies read on that resource. A key with write:cards can call GET /partner/cards, but cannot read members or other resources
• Admin grants all. The admin scope acts as a super-scope for everything
• Read cannot write. A read key cannot create, update, or delete anything
• Write scopes are isolated. write:clubs cannot read rewards, write:transactions cannot read staff

Permission presets

When creating a key in the dashboard, you choose from presets that map to scope arrays:

Member presets

Member keys have two presets:

Admin presets

Admin keys manage the platform:

Endpoint scope requirements

Partner CRUD resources share one pattern:

The pattern covers clubs (write:clubs), loyalty cards (write:cards), rewards (write:rewards), stamp cards (write:stamps), vouchers (write:vouchers), prepaid passes (write:passes), tiers (write:tiers), and staff (write:staff). Action endpoints, such as adding stamps or validating vouchers, require the same write scope as their resource.

See the Complete endpoint reference for the full per-endpoint listing with scopes, parameters, and response fields.

The groups below differ from the CRUD pattern:

Transactions

Redeeming a reward requires write:rewards, not write:transactions.

Members

Partner member endpoints are read-only. There is no write:members scope.

Member key endpoints

Following and unfollowing a card counts as a profile write. Both change the member's own "My Cards" collection, so they require write:profile.

Admin partners

Admin members

Admin analytics

Scope errors

When a key lacks the required scope:

{
  "error": true,
  "code": "AUTH_INSUFFICIENT_SCOPE",
  "message": "This action requires the 'write:cards' scope.",
  "retry_strategy": "no_retry",
  "details": {
    "required_scope": "write:cards"
  }
}

The retry_strategy is no_retry. The key cannot gain scopes at runtime. Create a new key with the required scopes instead.

Related topics

• Tool Discovery: Machine-readable tool definitions filtered by the key's scopes
• Enabling & Managing Keys: Create keys with the right presets
• Authentication: How the platform verifies keys
• Error Handling: Full error response format