Scopes

Overview

Every API key carries one or more scopes, and the API enforces them on every request. Scopes let you:

Limit blast radius if a key leaks or is misused.
Hand a dependent (third-party integration, BI tool, automation) only the access it actually needs.

Pick the narrowest scope set that covers your use case. The catalogue below describes every scope, and the recommended scope sets section lists sensible starting points for common integration patterns.

Scope vocabulary

Scopes have the shape resource:action, for example payouts:write. Two actions are defined today: read and write. Each endpoint requires one or more scopes following its resource and HTTP verb (GET /v1/payouts requires payouts:read; POST /v1/payouts requires payouts:write). You don’t have to memorise the rule. The authoritative list is GET /v1/scopes, and the required_scopes field on a 403 tells you exactly what an endpoint needs.

Catalogue

Scope	Description
`account_holders:read`	View account holders and status
`account_holders:write`	Create account holders
`account_programs:read`	View account programs and their lifecycle status
`accounts:read`	View accounts and holders
`accounts:write`	Create and manage accounts
`conversions:read`	View FX conversions
`conversions:write`	Initiate FX conversions
`deposits:read`	View deposits
`events:read`	View webhook events and their payloads
`payouts:read`	View payouts and their status
`payouts:write`	Initiate and manage payouts
`quotes:read`	View FX quotes (persisted and indicative)
`returns:read`	View deposit returns
`returns:write`	Initiate deposit returns
`transactions:read`	View transactions
`webhook_deliveries:read`	View webhook delivery history and outcomes
`webhook_deliveries:write`	Redeliver webhook deliveries
`webhook_subscriptions:read`	View webhook subscriptions
`webhook_subscriptions:write`	Create, modify, and delete webhook subscriptions; send test events

GET /v1/scopes is the live source of truth (public, no authentication required). The catalogue is filtered by your request’s api-version header, so the list reflects what’s available on the version you’re calling.

Aliases

Three aliases expand to a set of concrete scopes:

Alias	Expands to
`full_access`	Every scope in the catalogue
`read_only` / `*:read`	Every `:read` scope
`<resource>:*`	Every action for `<resource>` (e.g. `payouts:*`)

A full_access key automatically gains access to scopes added to the catalogue later. If you want a key whose budget is fixed at creation time, choose explicit scopes or a narrower alias.

Choosing scopes for a key

Scopes are picked at key-creation time in the Augustus Dashboard. Some starting points for common integration patterns:

Use case	Suggested scopes
Server-side payouts integration	`payouts:* events:read webhook_subscriptions:write webhook_deliveries:read`
Read-only BI / analytics	`read_only`
Webhook receiver only	`events:read webhook_deliveries:*`

When in doubt, start narrow. If a real call returns insufficient_scope, the error tells you exactly what’s missing, so widen and rotate the key.

Verifying & troubleshooting

Inspecting a key’s scopes

GET /v1/api_key returns the resolved scope set for the key authenticating the request. Useful at session start to plan within budget rather than discovering limits via 403 responses.

curl https://api.augustus.com/v1/api_key \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY"

import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus()
const apiKey = await client.apiKeys.introspect()

{
  "type": "api_key",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchant_id": "507f1f77bcf86cd799439011",
  "scopes": ["payouts:read", "payouts:write", "events:read"],
  "api_version": "2026-05-01"
}

Authorization errors

A request that doesn’t satisfy an endpoint’s required scopes is rejected with 403 insufficient_scope. The response carries a required_scopes array enumerating every scope the endpoint requires, regardless of what your key has:

{
  "category": "invalid_request_error",
  "code": "insufficient_scope",
  "message": "Insufficient scope to perform this operation.",
  "param": null,
  "required_scopes": ["payouts:write"],
  "doc_url": "https://docs.augustus.com/v1/errors",
  "correlation_id": "e5f6a7b8-c9d0-1234-ef01-234567890123"
}

Subtract your key’s scopes (from GET /v1/api_key) from required_scopes to know exactly what to add when you create the next key. insufficient_scope is distinct from permission_denied, which covers non-scope authorization failures such as IP allowlist mismatches or account approval state.

Rotating scopes

The scope set on an existing key is immutable. To change scopes, create a new key and revoke the old one. Recommended rollout:

Create a new key in the Augustus Dashboard with the new scope set.
Verify with GET /v1/api_key (using the new key) that scopes is what you expect.
Roll the new key out across your services (env var swap, secret rotation, etc.).
Revoke the old key in the dashboard once no traffic is using it.

Getting Started

Resources

Overview

Scope vocabulary

Catalogue

Aliases

Choosing scopes for a key

Verifying & troubleshooting

Inspecting a key’s scopes

Authorization errors

Rotating scopes

​Overview

​Scope vocabulary

​Catalogue

​Aliases

​Choosing scopes for a key

​Verifying & troubleshooting

​Inspecting a key’s scopes

​Authorization errors

​Rotating scopes

Overview

Scope vocabulary

Catalogue

Aliases

Choosing scopes for a key

Verifying & troubleshooting

Inspecting a key’s scopes

Authorization errors

Rotating scopes