> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Secure Your Blnk Server
> Enable secure mode, manage secret keys, and follow best practices for a secure environment.
export const CtaCallout = props => {
const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
const handleCtaClick = () => {
if (typeof window === "undefined" || !trackingEvent) {
return;
}
try {
window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
detail: {
name: trackingEvent,
href
}
}));
} catch {}
try {
window.posthog?.capture?.(trackingEvent, {
href
});
} catch {}
const gaPayload = {
cta_href: href
};
try {
window.gtag?.("event", trackingEvent, gaPayload);
} catch {}
try {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: trackingEvent,
...gaPayload
});
} catch {}
};
const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
const linkRel = isExternal ? rel : undefined;
return ;
};
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](/api-keys/overview).
Before you start, ensure you have a working instance of Blnk Core:
Local install or Blnk Cloud.
***
## Enable authentication
Enable secure mode by setting `server.secure` to `true` and providing a strong `server.secret_key`:
```bash blnk.env theme={"system"}
BLNK_SERVER_SECURE=true
BLNK_SERVER_SECRET_KEY=your_strong_secret_key
```
```json blnk.json theme={"system"}
{
"server": {
"secure": true,
"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:
```bash cURL wrap theme={"system"}
curl -X GET "http://localhost:5001/ledgers" \
-H "X-Blnk-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](/api-keys/overview), 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](/webhooks/global-webhooks) and [transaction hook](/webhooks/transaction-hooks) 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](/api-keys/owner-context).
3. **Manage hooks.** Register, update, list, and delete [transaction hooks](/webhooks/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](/webhooks/overview#webhook-security-signature-verification).
***
## 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.
* 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
* Exclude `blnk.json` from version control (`.gitignore`)
* Store sensitive configuration in environment variables
* Implement secure secret rotation procedures
* Follow the principle of least privilege: use scoped keys for services, not the master key
* Regularly review API key permissions. See [Manage API keys](/api-keys/manage-keys)
* Register and manage [transaction hooks](/webhooks/transaction-hooks) with the master key only
* Track failed authentication attempts
* Monitor API key usage patterns
* Set up alerts for suspicious activity
* Regularly review access logs
* 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.
| Code | When it happens |
| :--------------------- | :------------------------------------------------ |
| `AUTH_MISSING_API_KEY` | No `X-Blnk-Key` header was sent with the request. |
| `AUTH_INVALID_API_KEY` | The key value is unknown or malformed. |
| `AUTH_EXPIRED_API_KEY` | The key has expired or has been revoked. |
```json 401 Unauthorized wrap theme={"system"}
{
"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:
| Code | What to do |
| :--------------------- | :-------------------------------------------------------------------------------------------------- |
| `AUTH_MISSING_API_KEY` | Add the `X-Blnk-Key` header to your request. |
| `AUTH_INVALID_API_KEY` | Verify the key value wasn't truncated or swapped with another environment's key. |
| `AUTH_EXPIRED_API_KEY` | Create a replacement key before revoking the old one. See [Manage API keys](/api-keys/manage-keys). |
Permission errors for missing scopes are covered in [Scopes](/api-keys/scopes#error-handling). Owner and delegation errors are covered in [Owner context](/api-keys/owner-context#error-handling).
***
## Related docs
Create and use scoped keys.
Pick the right permissions.
Owner labels and cross-owner admin.
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](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).
Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.