Skip to main content
This guide walks you through running your Blnk server in secure mode and protecting your master key. For day-to-day API access, create scoped API keys. Before you start, ensure you have a working instance of Blnk Core:

Deploy Blnk

Local install or Blnk Cloud.

​
Enable authentication

Enable secure mode by setting server.secure to true and providing a strong server.secret_key: 
BLNK_SERVER_SECURE=true
BLNK_SERVER_SECRET_KEY=your_strong_secret_key
When secure mode is enabled, every API request must include a valid key in the X-Blnk-Key header. Requests without a key are rejected. The secret_key value becomes your master key. It has full access to every endpoint on the server, so use it only for administrative tasks and initial setup. For regular service traffic, create scoped API keys. Pass the master key in the X-Blnk-Key header:
cURL
curl -X GET "http://localhost:5001/ledgers" \
  -H "X-Blnk-Key: <master-key>"
Do not commit the master key to version control. In production, store it in a secret manager or inject it through environment variables.

​
About the master key

The master key is the secret_key from your configuration. Unlike scoped API keys, it is not bound to an owner or scopes, and it can call any endpoint on the server. Blnk also uses it to sign outbound webhook and transaction hook deliveries. We recommend using the master key only for initial setup and administrative tasks listed below. For regular API calls, use the scoped keys you create.
  1. Create scoped keys. Create your first scoped keys with POST /api-keys. After that, services should use scoped keys, not the master key.
  2. Manage keys across owners. List, create, and revoke keys for any owner by passing owner in the request. Scoped keys can manage keys only within their own owner_id. See Owner context.
  3. Manage hooks. Register, update, list, and delete transaction hooks. Hook management rejects scoped keys, even with hooks:* scopes.
  4. Verify webhooks. Blnk signs outbound deliveries with X-Blnk-Signature using server.secret_key. Use the same secret on your receiver to verify authenticity. See Webhook security.

​
Security check list

Enabling secure mode is only the start. Work through this checklist to protect your master key, keep configuration out of version control, and limit API access to what each service needs.
1

Master key management

  • Use a strong, randomly generated master key
  • Never share or commit it to version control
  • Store it in environment variables or a secret management tool
  • Rotate it on a regular schedule
2

Configuration management

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

Access control

  • Follow the principle of least privilege: use scoped keys for services, not the master key
  • Regularly review API key permissions. See Manage API keys
  • Register and manage transaction hooks with the master key only
4

Monitoring and auditing

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

Regular updates

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

​
Error handling

Structured errors are available from Blnk Core 0.15.0 and later.
When authentication fails, Blnk returns 401 Unauthorized. These errors apply whether you use the master key or a scoped key.
CodeWhen it happens
AUTH_MISSING_API_KEYNo X-Blnk-Key header was sent with the request.
AUTH_INVALID_API_KEYThe key value is unknown or malformed.
AUTH_EXPIRED_API_KEYThe key has expired or has been revoked.
401 Unauthorized
{
  "error": "Authentication required. Use X-Blnk-Key header",
  "error_detail": {
    "code": "AUTH_MISSING_API_KEY",
    "message": "Authentication required. Use X-Blnk-Key header"
  }
}
To resolve the error:
CodeWhat to do
AUTH_MISSING_API_KEYAdd the X-Blnk-Key header to your request.
AUTH_INVALID_API_KEYVerify the key value wasn’t truncated or swapped with another environment’s key.
AUTH_EXPIRED_API_KEYCreate a replacement key before revoking the old one. See Manage API keys.
Permission errors for missing scopes are covered in Scopes. Owner and delegation errors are covered in Owner context.

Scoped API keys

Create and use scoped keys.

Scopes

Pick the right permissions.

Owner context

Owner labels and cross-owner admin.

Manage keys

List, revoke, and delegate keys.

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