Secure your Blnk server

​

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:

​

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.

{
  "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 -H "X-Blnk-Key: your_strong_secret_key" https://yourdomain.com:5001/ledgers

​

Generating fine-grained API keys

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:

curl -X POST -H "X-Blnk-Key: your_strong_secret_key" -H "Content-Type: application/json" \
-d '{
  "name": "Service Account",
  "owner": "service_name",
  "scopes": ["ledgers:read", "balances:write"],
  "expires_at": "2026-03-11T00:00:00Z"
}' https://yourdomain.com:5001/api-keys

​

Use the API key

curl -H "X-Blnk-Key: your_api_key" https://yourdomain.com:5001/ledgers

​

Understanding Scopes

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

​

Available resources

​

Available actions

​

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:

​

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.

Love building with Blnk? We’d love to hear your feedback. Tell us here.