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

# Server and Security Configuration

> Configure server runtime, secure mode, tokenization, and rate limiting in Blnk.

This page covers the configuration used to control how the Blnk server listens for requests, protects access to the API, and enables tokenization for sensitive identity fields.

***

## Server settings

Use the server settings below to configure how Blnk exposes its API and enforces authentication.

<CodeGroup>
  ```bash blnk.env theme={"system"}
  BLNK_SERVER_SECURE=false
  BLNK_SERVER_SECRET_KEY=
  BLNK_SERVER_PORT=5001
  ```

  ```json blnk.json theme={"system"}
  {
    "server": {
      "secure": false,
      "secret_key": "",
      "port": "5001"
    }
  }
  ```
</CodeGroup>

|                          | Description                                                 | Default |
| :----------------------- | :---------------------------------------------------------- | :------ |
| `BLNK_SERVER_SECURE`     | Enables additional secure-mode protections for the server.  | `false` |
| `BLNK_SERVER_SECRET_KEY` | Secret used for signing and other cryptographic operations. | None    |
| `BLNK_SERVER_PORT`       | The port Blnk listens on for incoming HTTP requests.        | `5001`  |

### `BLNK_SERVER_SECURE`

This controls whether API authentication is enforced when you make requests to the server. When set to `false`, Blnk skips authentication checks.

When set to `true`, requests must authenticate via `X-Blnk-Key` header using one of the following:

* the master key, `BLNK_SERVER_SECRET_KEY`
* a stored API key

  <Card title="API keys" icon="key" href="/advanced/secure-blnk#api-keys">
    Learn how to create and manage API keys with custom permissions for secure requests.
  </Card>

### `BLNK_SERVER_SECRET_KEY`

This is required for any secure Blnk deployment. It is used in two places in Blnk:

1. As the master API key for authenticated requests to the server
2. As the HMAC signing secret for outgoing webhooks and hook callbacks.

   <Card title="Webhook security" icon="shield" href="/advanced/notifications#webhook-security-signature-verification">
     Learn how to verify webhook signatures and protect webhook consumers.
   </Card>

This means the same secret affects both request authentication and webhook signature validation on systems receiving Blnk webhooks.

<Warning>
  Make sure to keep `BLNK_SERVER_SECRET_KEY` out of version control. Store it in a secret manager or inject it through environment variables in production.
</Warning>

### Best practices

1. Set `BLNK_SERVER_SECURE=true` in any real deployment.
2. Use a strong secret for `BLNK_SERVER_SECRET_KEY`, and make sure to store secrets outside version control.
3. Keep the server secret stable within an environment unless you are prepared to update any systems that verify webhook signatures.

***

## Tokenization settings

Use tokenization settings to enable encryption and token generation when using the [PII Tokenization](/identities/pii-tokenization) feature.

<CodeGroup>
  ```bash blnk.env theme={"system"}
  BLNK_TOKENIZATION_SECRET="blnk-pii-secret"
  ```

  ```json blnk.json theme={"system"}
  {
    "tokenization_secret": "blnk-pii-secret"
  }
  ```
</CodeGroup>

|                            | Description                                                                                                                                      | Default             |
| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |
| `BLNK_TOKENIZATION_SECRET` | Enables tokenization for sensitive identity fields. Must be exactly 32 bytes long. Used as the cryptographic secret for tokenization operations. | Disabled when unset |

### Tokenization behaviour

Tokenization is only enabled when `BLNK_TOKENIZATION_SECRET` is set and is exactly 32 bytes long. If the secret is missing, tokenization is disabled. If the secret is set but not 32 bytes long, Blnk does not fail startup, but tokenization operations may fail when called.

When enabled, Blnk uses this secret for AES-GCM encryption in standard tokenization and HMAC-based seeding for format-preserving tokenization.

<Note>
  **Note:** Store this secret securely and keep it stable for each environment. If you change it after data has already been tokenized, previously tokenized values may no longer detokenize correctly.
</Note>

***

## Rate limiting

Use rate limiting settings to protect the API from abuse and to control traffic spikes more predictably.

<CodeGroup>
  ```bash blnk.env theme={"system"}
  BLNK_RATE_LIMIT_RPS=5000000
  BLNK_RATE_LIMIT_BURST=10000000
  BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC=10800
  ```

  ```json blnk.json theme={"system"}
  {
    "rate_limit": {
      "requests_per_second": 5000000,
      "burst": 10000000,
      "cleanup_interval_sec": 10800
    }
  }
  ```
</CodeGroup>

|                                        | Description                                               | Default    |
| :------------------------------------- | :-------------------------------------------------------- | :--------- |
| `BLNK_RATE_LIMIT_RPS`                  | Maximum requests allowed per second per client.           | `5000000`  |
| `BLNK_RATE_LIMIT_BURST`                | Maximum short burst allowed above the RPS limit.          | `10000000` |
| `BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC` | Cleanup interval for expired rate-limit data, in seconds. | `10800`    |

### Rate limiting behaviour

If both `BLNK_RATE_LIMIT_RPS` and `BLNK_RATE_LIMIT_BURST` are unset, Blnk applies its built-in defaults.

If you set only one of those two values, Blnk derives the other automatically:

* if only `BLNK_RATE_LIMIT_RPS` is set, `burst` defaults to `2 * RPS`
* if only `BLNK_RATE_LIMIT_BURST` is set, `requests_per_second` defaults to `burst / 2`

<Tip>
  **Tip:** Start with the defaults unless you have a clear traffic policy or abuse-prevention requirement.
</Tip>

***

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