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

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

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

Actions

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.

POST /{id}/metadata maps to the metadata resource. A scoped key needs metadata:write to update metadata.

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.