API Key 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
Key administration	`api-keys:read`, `api-keys:write`, `api-keys:delete`	Manage keys within its owner context

Avoid *:* unless you truly need full access. For most cases, create a scoped key with only the permissions required.

How scopes work

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

Resources
Actions

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

You can use * as a wildcard on either side. ledgers:* grants all ledger actions. *:read grants read access to every resource.

Hook management requires the master key. Scoped keys cannot manage hooks.

Error handling

Structured errors are available from Blnk Core 0.15.0 and later.

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.

403 Forbidden

{
  "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.

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.

Scoped API Keys

API Key Owner Context

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

How scopes work

Error handling

Need help?

​How scopes work

​Error handling

​Need help?

How scopes work

Error handling

Need help?