Operating

API Key Scopes

Choose the right permissions for each API key using 'resource:action' scopes.

Scopes control what an API key is allowed to do.

Each scope uses resource:action format. For example, ledgers:read allows a key to read ledgers, while transactions:write allows it to create transactions.

Instead of giving every service full access, use scopes to create keys that match what each service actually does.

These patterns cover most setups:

Use case	Scopes	What the key can do
Read-only reporting	`ledgers:read`, `balances:read`	View ledgers and balances
Payment processing	`transactions:write`, `balances:read`	Create transactions and check balances
Identity management	`identities:write`, `identities:read`	Create and view identities
Metadata updates	`metadata:write`	Update metadata on ledgers, transactions, identities, and balances
Key administration	`api-keys:read`, `api-keys:write`, `api-keys:delete`	Manage keys within its owner context

How scopes work

Each scope has two parts: a resource and an action, separated by a colon: resource:action.

The resource defines the area of Blnk the key can access. The action defines what the key can do in that area.

Resource	Description
`*`	All resources
`ledgers`	Ledger management
`balances`	Balance operations
`accounts`	Account operations
`identities`	Identity management
`transactions`	Transaction processing
`balance-monitors`	Balance monitoring
`api-keys`	API key management
`search`	Search operations
`reconciliation`	Reconciliation tasks
`metadata`	Metadata management
`backup`	Backup operations

Blnk maps HTTP methods to actions automatically:

Action	HTTP methods	Description
`*`	Any	All actions on the resource
`read`	`GET`, `HEAD`	View operations
`write`	`POST`, `PUT`, `PATCH`	Create and modify operations
`delete`	`DELETE`	Delete operations

Error handling

When a scoped key is valid but lacks permission for the endpoint you called, Blnk returns a 403 Forbidden response.

Code	When it happens
`AUTH_INSUFFICIENT_PERMISSIONS`	The key is missing the scope required for that endpoint.
`AUTH_UNKNOWN_RESOURCE`	The request path does not map to a known Blnk resource.
`AUTH_MASTER_KEY_REQUIRED`	The endpoint requires the master key, such as hook management.

{
  "error": "Insufficient permissions for transactions:write",
  "error_detail": {
    "code": "AUTH_INSUFFICIENT_PERMISSIONS",
    "message": "Insufficient permissions for transactions:write"
  }
}

To resolve the error:

Code	What to do
`AUTH_INSUFFICIENT_PERMISSIONS`	Check which scope the endpoint needs, then create a new key with that scope or call an endpoint the key already covers.
`AUTH_UNKNOWN_RESOURCE`	Verify the request path matches a supported API route.
`AUTH_MASTER_KEY_REQUIRED`	Use the master key for that operation.