Skip to main content
POST
/
api-keys
curl --request POST \
  --url http://localhost:5001/api-keys \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "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
}

​
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, 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).
​
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 --request POST \
  --url http://localhost:5001/api-keys \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "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
}

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