Create API key

How to create a new API key with fine-grained permissions in Blnk.

Overview

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 master key authentication (the server.secret_key from your configuration).

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: Secure your Blnk server

Body

name · string · required

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

owner · string · required

Unique identifier of the owner or service associated with the API key. This helps track which service or team owns each key.

scopes · 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

expires_at · string · required

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

Response

api_key_id · string

Unique identifier for the created API key.

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.

name · string

The name of the API key.

owner_id · string

The owner identifier associated with the API key.

scopes · array

List of permissions granted to the API key.

expires_at · string

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

created_at · string

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

last_used_at · 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.

is_revoked · boolean

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

curl -X POST \
  -H "X-Blnk-Key: your_master_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"
  }' \
  https://YOUR_BLNK_INSTANCE_URL:5001/api-keys

201

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

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.

---

Tip: Connect to Blnk Cloud to see your Core data.

You can view your transactions, manage identities, create custom reports, invite other team members to collaborate, and perform operations on your Core — all in one dashboard.

Check out Blnk Cloud →