Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.augustus.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

ScopeDescription
payouts:readView payouts and their status
payouts:writeInitiate and manage payouts
deposits:readView deposits
returns:readView deposit returns
returns:writeInitiate deposit returns
conversions:readView FX conversions
conversions:writeInitiate FX conversions
quotes:readView FX quotes (persisted and indicative)
accounts:readView accounts and holders
accounts:writeCreate and manage accounts
account_programs:readView account programs and their lifecycle status
webhook_subscriptions:readView webhook subscriptions
webhook_subscriptions:writeCreate, modify, and delete webhook subscriptions; send test events
events:readView webhook events and their payloads
webhook_deliveries:readView webhook delivery history and outcomes
webhook_deliveries:writeRedeliver webhook deliveries
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:
AliasExpands to
full_accessEvery scope in the catalogue
read_only / *:readEvery :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 caseSuggested scopes
Server-side payouts integrationpayouts:* events:read webhook_subscriptions:write webhook_deliveries:read
Read-only BI / analyticsread_only
Webhook receiver onlyevents: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"

{
  "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:
  1. Create a new key in the Augustus Dashboard with the new scope set.
  2. Verify with GET /v1/api_key (using the new key) that scopes is what you expect.
  3. Roll the new key out across your services (env var swap, secret rotation, etc.).
  4. Revoke the old key in the dashboard once no traffic is using it.