Skip to main content

​
Overview

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

Start here to run your Blnk server

​
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

This requires the master key authentication. 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.
ownerUnique identifier of the owner or service associated with the API key, provided by you. You can use any string value that identifies the owner (e.g., team name, service name, user ID).
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.

​
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
hooksWebhook management
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

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

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