Skip to main content
This guide will walk you through the steps to run your Blnk server in secure mode and implement best practices for maintaining a secure environment. Before you start, please ensure that you have a working instance of Blnk Core:

Deploy Blnk

Local install or Blnk Cloud.

​
Enable secure mode

Modify your blnk.json configuration file to enable secure mode. Set server.secure to true and provide a strong server.secret_key.
blnk.json
{
  "server": {
    "secure": true,
    "secret_key": "your_strong_secret_key"
  }
}

​
Authentication methods

Blnk supports authentication via the X-Blnk-Key header.

​
Master key authentication

The master key (server.secret_key) provides full access to all API endpoints. Use it only for administrative tasks and initial setup. 
curl --request GET \
  --url http://localhost:5001/ledgers \
  --header 'X-blnk-key: <api-key>'

​
Generating fine-grained API keys

Available on version 0.10.1 or later.
For regular operations, create API keys with specific permissions to enforce fine-grained access control.

​
Create an API key

Use the master key to bootstrap keys for each owner. Starting in 0.14.3, a non-master key with api-keys:write can also create keys, but only within its own owner context and with scopes it already holds. See the Create API key reference for complete documentation. 
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"
  }'
ParameterDescription
nameThe name of the API key or service account.
ownerOwner identifier for the new key. You choose this value (e.g. team name, service name, user ID). It is stored as owner_id on the key record and defines the key’s owner context. When you authenticate with a non-master API key, Blnk always uses the caller’s owner_id — a different owner value in the request returns 403 Forbidden.
scopesA list of permissions granted to the API key (e.g., ledgers:read, balances:write).
expires_atThe expiration date and time for the API key in ISO 8601 format.
For managing API keys, see the API Keys reference documentation: create, list, and delete API keys.

​
Owner context

Available on version 0.14.3 or later.
Every stored API key belongs to an owner context — the owner_id field on the key record. When you call the API key management endpoints (create, list, revoke), Blnk checks whether the caller is allowed to act on that owner.
CallerWhat it can manage
Master key (server.secret_key)Keys for any owner. Pass owner in the request to target a specific owner. The master key is a global server secret and is not bound to an owner_id.
Non-master API keyKeys for its own owner_id only. Blnk resolves the effective owner from the authenticated key, not from caller-supplied owner values.
For example, key k1 has owner_id = merchant_a.
  • k1 can create, list, and revoke keys for merchant_a
  • k1 cannot manage keys for merchant_b, even if the request body or query includes "owner": "merchant_b"
  • The master key can manage keys for both merchant_a and merchant_b
Non-master keys with api-keys:read, api-keys:write, or api-keys:delete can delegate key management within their owner context, subject to two additional rules:
  • Scope inheritance: A non-master key can grant only scopes it already holds. You cannot mint a key with broader permissions than the caller.
  • No cross-owner access: The effective owner always comes from the caller’s owner_id, never from a different value in the request.

​
Use the API key

curl --request GET \
  --url http://localhost:5001/ledgers \
  --header 'X-blnk-key: <api-key>'

​
Understanding Scopes

Scopes define what resources an API key can access and what actions it can perform, formatted as resource:action.

​
Available resources

ResourcesDescription
*All resources
ledgersLedger management
balancesBalance operations
accountsAccount operations
identitiesIdentity management
transactionsTransaction processing
balance-monitorsBalance monitoring
hooksHook-related permissions (hook management endpoints require the master key as of 0.14.3)
api-keysAPI key management
searchSearch operations
reconciliationReconciliation tasks
metadataMetadata management
backupBackup operations

​
Available actions

ActionsDescription
*All actions
readView operations — GET/HEAD
writeModify operations — POST/PUT/PATCH
deleteDelete operations — DELETE

​
Examples

  • ledgers:read: Can only view ledgers
  • transactions:write: Can create/modify transactions
  • *:*: Full access to all resources and actions

​
Security best practices

​
Master key management

  • Use a strong, randomly generated master key
  • Never share or commit it to version control
  • Store it in environment variables or secret management tools
  • Rotate keys regularly

​
API key management

  • Create separate API keys for different services
  • Set expiration dates for API keys
  • Grant only necessary scopes
  • Regularly audit and revoke unused keys
  • Monitor API key usage

​
Configuration management

  • Exclude blnk.json from version control (.gitignore)
  • Store sensitive configurations in environment variables
  • Implement secure secret rotation procedures

​
Access control

  • Follow the principle of least privilege
  • Regularly review API key permissions
  • Implement role-based access control (RBAC)
  • Maintain audit logs of key activities
  • Register and manage transaction hooks with the master key only

​
Monitoring and auditing

  • Track failed authentication attempts
  • Monitor API key usage patterns
  • Set up alerts for suspicious activity
  • Regularly review access logs

​
Regular updates

  • Keep all components up to date
  • Monitor security advisories
  • Schedule regular maintenance windows

​
Error handling

Authentication failures return specific error messages:
Status CodeMessage
401 Unauthorized”Authentication required. Use X-Blnk-Key header”
“Invalid API key”
“API key is expired or revoked”
403 Forbidden”Insufficient permissions for resource:action”
“Unknown resource type”
“cannot manage API keys for another owner”
“cannot grant scopes broader than caller”
“hook management requires master key”

​
Example error response

{
  "error": "Insufficient permissions for transactions:write"
}

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