Scopes & Permissions.

Scopes define what an agent key is allowed to do. Every agent endpoint checks the request's key for the required scope before executing. If the key lacks the required scope, the request is rejected with a 403 error.

How Scopes Work

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

1. Controller checks which scope(s) the endpoint requires
2. The key's scopes are compared against the requirement
3. If any required scope matches, access is granted (OR-logic)
4. If no scope matches, a 403 AUTH_INSUFFICIENT_SCOPE error is returned

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 only affect the key owner's data.

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 logical 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 --> J["write:tiers"]
    C --> K["write:staff"]

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

Important behaviors:

• 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-only 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 simpler presets:

Admin Presets

Admin keys manage the platform:

Endpoint Scope Requirements

Clubs

Loyalty Cards

Rewards

Transactions

Members

Stamp Cards

Vouchers

Tiers

Staff

Member Profile

Member Balance & Cards

Member Transactions

Member Rewards

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 dynamically. Create a new key with the required scopes instead.

Admin Partners

Admin Members

Admin Analytics

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 keys are verified
• Error Handling — Full error response format