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 yourblnk.json
configuration file to enable secure mode. Set server.secure
to true and provide a strong server.secret_key
.
blnk.json
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.
Generating fine-grained API keys
Available on version 0.10.1 or later.
Create an API key
This requires the master key authentication:Parameter | Description |
---|---|
name | The name of the API key or service account. |
owner | Unique identifier of the owner or service associated with the API key. |
scopes | A list of permissions granted to the API key (e.g., ledgers:read , balances:write ). |
expires_at | The expiration date and time for the API key in ISO 8601 format. |
Use the API key
Understanding Scopes
Scopes define what resources an API key can access and what actions it can perform, formatted asresource:action
.
Available resources
Resources | Description |
---|---|
* | All resources |
ledgers | Ledger management |
balances | Balance operations |
identities | Identity management |
transactions | Transaction processing |
balance-monitors | Balance monitoring |
hooks | Webhook management |
api-keys | API key management |
search | Search operations |
reconciliation | Reconciliation tasks |
metadata | Metadata management |
backup | Backup operations |
Available actions
Actions | Description |
---|---|
* | All actions |
read | View operations — GET/HEAD |
write | Modify operations — POST/PUT/PATCH |
delete | Delete operations — DELETE |
Examples
ledgers:read
: Can only view ledgerstransactions: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 Code | Message |
---|---|
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” |