Create API Key

POST

api-keys

curl -X POST "http://localhost:5001/api-keys" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Account",
    "owner": "owner_id",
    "scopes": ["ledgers:read", "balances:write"],
    "expires_at": "2026-03-11T00:00:00Z"
  }'

{
  "api_key_id": "api_key_879f0ecb-e29f-4137-801b-1048366381db",
  "key": "YVLIhuIplUzLRCcT9r7DQ_jsGKCXAn39JQ3n_o-Ll2Q=",
  "name": "Service Account",
  "owner_id": "owner_id",
  "scopes": ["ledgers:read", "balances:write"],
  "expires_at": "2026-03-11T00:00:00Z",
  "created_at": "2025-11-18T13:39:50.390457762Z",
  "last_used_at": "0001-01-01T00:00:00Z",
  "is_revoked": false
}

{
  "error": "owner is required",
  "error_detail": {
    "code": "APIKEY_OWNER_REQUIRED",
    "message": "owner is required"
  }
}

{
  "error": "cannot grant scopes broader than caller",
  "error_detail": {
    "code": "AUTH_SCOPE_ESCALATION",
    "message": "cannot grant scopes broader than caller"
  }
}

API keys allow you to enforce access control by granting specific scopes (permissions) to different services or applications, rather than using the master key for all operations.

Available on version 0.10.1 or later. Requires the master key or an API key with api-keys:write scope.

If you’re using the auto-provisioned Enterprise Core instance included with your Production License deployment, set the base URL to: https://ENTERPRISE_PUBLIC_URL/core.If you’re connecting to a different Core instance, use the publicly accessible base URL for that instance instead.

Authorization

If set, the API uses an API key for authentication. Include the following header in your requests: X-blnk-key: <api-key>. Replace <api-key> with your secret API key. Ensure the key is kept secure and not exposed in public repositories or client-side code. See also: Scoped API keys and Secure your Blnk server.

Body

string

required

The name of the API key or service account. Use descriptive names to identify the purpose of each key.

string

required

Unique identifier of the owner or service associated with the API key, provided by you. This helps track which service or team owns each key. You can use any string value that identifies the owner (e.g., team name, service name, user ID).

array

required

A list of permissions granted to the API key. Each scope follows the format resource:action. See Understanding Scopes for available resources and actions.Examples:

["ledgers:read"] - Can only view ledgers
["transactions:write", "balances:read"] - Can create/modify transactions and view balances
["*:*"] - Full access to all resources and actions

string

required

The expiration date and time for the API key in ISO 8601 format (e.g., "2026-03-11T00:00:00Z").

Response

string

Unique identifier for the created API key.

string

The actual API key value. Store this securely as it will not be shown again. Use this value in the X-Blnk-Key header for authenticated requests.

The api_key value is only returned once when the key is created. If you lose it, you’ll need to create a new API key. Never commit API keys to version control or expose them in client-side code.

string

The name of the API key.

string

The owner identifier associated with the API key.

array

List of permissions granted to the API key.

string

The expiration date and time for the API key in ISO 8601 format.

string

ISO 8601 formatted timestamp of when the API key was created.

string

ISO 8601 formatted timestamp of when the API key was last used for authentication. Returns "0001-01-01T00:00:00Z" if the key has never been used.

boolean

Whether the API key has been revoked. Returns false for newly created keys.

curl -X POST "http://localhost:5001/api-keys" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Account",
    "owner": "owner_id",
    "scopes": ["ledgers:read", "balances:write"],
    "expires_at": "2026-03-11T00:00:00Z"
  }'

{
  "api_key_id": "api_key_879f0ecb-e29f-4137-801b-1048366381db",
  "key": "YVLIhuIplUzLRCcT9r7DQ_jsGKCXAn39JQ3n_o-Ll2Q=",
  "name": "Service Account",
  "owner_id": "owner_id",
  "scopes": ["ledgers:read", "balances:write"],
  "expires_at": "2026-03-11T00:00:00Z",
  "created_at": "2025-11-18T13:39:50.390457762Z",
  "last_used_at": "0001-01-01T00:00:00Z",
  "is_revoked": false
}

{
  "error": "owner is required",
  "error_detail": {
    "code": "APIKEY_OWNER_REQUIRED",
    "message": "owner is required"
  }
}

{
  "error": "cannot grant scopes broader than caller",
  "error_detail": {
    "code": "AUTH_SCOPE_ESCALATION",
    "message": "cannot grant scopes broader than caller"
  }
}

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.

Delete hooks

List API keys

curl -X POST "http://localhost:5001/api-keys" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Account",
    "owner": "owner_id",
    "scopes": ["ledgers:read", "balances:write"],
    "expires_at": "2026-03-11T00:00:00Z"
  }'

{
  "api_key_id": "api_key_879f0ecb-e29f-4137-801b-1048366381db",
  "key": "YVLIhuIplUzLRCcT9r7DQ_jsGKCXAn39JQ3n_o-Ll2Q=",
  "name": "Service Account",
  "owner_id": "owner_id",
  "scopes": ["ledgers:read", "balances:write"],
  "expires_at": "2026-03-11T00:00:00Z",
  "created_at": "2025-11-18T13:39:50.390457762Z",
  "last_used_at": "0001-01-01T00:00:00Z",
  "is_revoked": false
}

{
  "error": "owner is required",
  "error_detail": {
    "code": "APIKEY_OWNER_REQUIRED",
    "message": "owner is required"
  }
}

{
  "error": "cannot grant scopes broader than caller",
  "error_detail": {
    "code": "AUTH_SCOPE_ESCALATION",
    "message": "cannot grant scopes broader than caller"
  }
}

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Transaction hooks

API keys

System

Authorization

Body

Response

Need help?

​Authorization

​Body

​Response

​Need help?

Authorization

Body

Response

Need help?