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

## 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:

<Card title="Deploy Blnk" icon="sparkles" href="/home/install">
  Start here to run your Blnk server
</Card>

***

## 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`.

```json blnk.json theme={"system"}
{
  "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.

```bash theme={"system"}
curl --request GET \
  --url http://localhost:5001/ledgers \
  --header 'X-blnk-key: <api-key>'
```

### Generating fine-grained API keys

<Info>Available on version 0.10.1 or later.</Info>

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/create-api-key) reference for complete documentation.

```json theme={"system"}
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"
  }'
```

| 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, provided by you. You can use any string value that identifies the owner (e.g., team name, service name, user ID). |
| `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.                                                                                                                         |

<Tip>
  For managing API keys, see the [API Keys reference documentation](/reference/create-api-key): create, list, and delete API keys.
</Tip>

#### Use the API key

```bash theme={"system"}
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

| **Resources**      | **Description**        |
| :----------------- | :--------------------- |
| `*`                | All resources          |
| `ledgers`          | Ledger management      |
| `balances`         | Balance operations     |
| `accounts`         | Account 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 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 Code**      | **Message**                                                                                                      |
| :------------------- | :--------------------------------------------------------------------------------------------------------------- |
| **401 Unauthorized** | "Authentication required. Use X-Blnk-Key header" <br /> "Invalid API key" <br /> "API key is expired or revoked" |
| **403 Forbidden**    | "Insufficient permissions for resource:action" <br /> "Unknown resource type"                                    |

### Example error response

```json theme={"system"}
{
  "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](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).

***

<Tip>
  **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 →](https://www.blnkfinance.com/products/cloud)
</Tip>