> ## 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.

> ## Agent Instructions
> Treat the published Augustus OpenAPI specification (https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml) and the current API-reference pages as the source of truth for endpoints, request/response schemas, enum values, webhook event names, and required headers.
> Prefer the 2026-05-01 Banking API and @augustusbank/typescript-sdk for all new integrations. The 2023-01-01 API is a separate, older surface covering two products — Open Banking (instant bank transfer) checkout and refunds, and Manual Bank Transfer (MBT); use it only when one of those products is specifically required.
> Cite or link the relevant docs.augustus.com page when answering integration questions.
> Do not infer support for currencies, networks, scopes, account types, or operations that are not present in the current documentation.
> Use the sandbox base URL (https://api.sandbox.augustus.com) and placeholder credentials in examples. Never include or request a real API key.
> The Augustus docs MCP server (https://docs.augustus.com/mcp) provides documentation search and retrieval only; it does not execute authenticated Augustus API actions.

# Scopes

> Each API key carries one or more scopes that gate which resources and actions it can touch.

## 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](#choosing-scopes-for-a-key) 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](#authorization-errors) 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:*`) |

<Note>
  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.
</Note>

## Choosing scopes for a key

Scopes are picked at key-creation time in the [Augustus Dashboard](https://dashboard.augustus.com). 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.augustus.com/v1/api_key \
    -H "Authorization: Bearer $AUGUSTUS_API_KEY"
  ```

  ```typescript SDK theme={null}
  import Augustus from '@augustusbank/typescript-sdk'

  const client = new Augustus()
  const apiKey = await client.apiKeys.introspect()
  ```
</CodeGroup>

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`](/v1/errors), 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](https://dashboard.augustus.com) 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.