Scopes & permissions.

The Partner key creation form selects View only by default. Choose a write preset explicitly when the integration needs it. Existing grants remain unchanged.

Scopes define what an Integration API 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. Most endpoints accept any listed scope. Monetary prepaid-pass writes require both write:passes and write:pass-money as literal grants.
4. If the key does not meet the requirement, the platform returns a 403 AUTH_INSUFFICIENT_SCOPE error.

Available scopes

Read scope

For partner and member keys, read permits the read endpoints for that key's role. Admin keys use read:partners, read:members, and read:analytics. A scope never changes a key's role.

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 satisfies ordinary scope checks within the key's role. Monetary pass writes still require both explicit grants: write:passes and write:pass-money. Ownership, entitlement, and business rules still apply.

Admin scopes

Admin keys have platform-level scopes:

Scope hierarchy

Scopes follow a hierarchy:

graph LR
    A["admin"] -->|"ordinary scopes"| B["read"]
    A --> C["Resource write scopes"]
    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 ordinary scopes. Monetary pass writes also require both explicit monetary grants
• 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:

The partner key form has a separate Allow monetary prepaid pass writes checkbox, unchecked by default. Selecting it adds both monetary write scopes to the chosen preset. The presets above alone do not grant monetary writes, including Full access. Read access to money balances uses pass_format=2 and the existing read permission.

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:

Monetary prepaid passes

Monetary product writes, sale, spend, and spend reversal require write:passes and write:pass-money, plus pass_format=2. Neither admin nor either write scope alone meets that requirement. Member keys remain read-only for pass balances. Refund and correction actions have no Agent endpoint. See monetary pass calls.

Apple Wallet settings

See the Apple Wallet API for item types and fields.

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