Skip to main content
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 caseScopesWhat the key can do
Read-only reportingledgers:read, balances:readView ledgers and balances
Payment processingtransactions:write, balances:readCreate transactions and check balances
Identity managementidentities:write, identities:readCreate and view identities
Key administrationapi-keys:read, api-keys:write, api-keys:deleteManage 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.
The resource defines the area of Blnk the key can access. The action defines what the key can do in that area.
ResourceDescription
*All resources
ledgersLedger management
balancesBalance operations
accountsAccount operations
identitiesIdentity management
transactionsTransaction processing
balance-monitorsBalance monitoring
api-keysAPI key management
searchSearch operations
reconciliationReconciliation tasks
metadataMetadata management
backupBackup 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.
CodeWhen it happens
AUTH_INSUFFICIENT_PERMISSIONSThe key is missing the scope required for that endpoint.
AUTH_UNKNOWN_RESOURCEThe request path does not map to a known Blnk resource.
AUTH_MASTER_KEY_REQUIREDThe 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:
CodeWhat to do
AUTH_INSUFFICIENT_PERMISSIONSCheck which scope the endpoint needs, then create a new key with that scope or call an endpoint the key already covers.
AUTH_UNKNOWN_RESOURCEVerify the request path matches a supported API route.
AUTH_MASTER_KEY_REQUIREDUse the master key for that operation.

Overview

Create and use scoped keys.

Owner context

How Blnk isolates key management.

Manage keys

List, revoke, and delegate keys.

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