Server and Security Configuration

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.

BLNK_SERVER_SECURE=false
BLNK_SERVER_SECRET_KEY=
BLNK_SERVER_PORT=5001
BLNK_METRICS_BEARER_TOKEN=

{
  "server": {
    "secure": false,
    "secret_key": "",
    "port": "5001",
    "metrics_bearer_token": ""
  }
}

	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_METRICS_BEARER_TOKEN`	Bearer token required to access `/metrics` when set. See Metrics endpoint.	None

`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
API keys
Scoped keys for day-to-day API access.

`BLNK_SERVER_SECRET_KEY`

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

As the master API key for authenticated requests to the server
As the HMAC signing secret for outgoing webhooks and hook callbacks.
Webhook security
Signature verification for webhook consumers.

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

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.

Best practices

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

Metrics endpoint

When monitoring export is enabled, Blnk serves Prometheus metrics at GET /metrics on the API port and on the worker monitoring port. Set metrics_bearer_token to require Authorization: Bearer <token> on scrape requests.

`server.secure`	Token set	`/metrics` access
`false`	no	Open
`false`	yes	Bearer required
`true`	yes	Bearer required
`true`	no	Blocked

The same rules apply on the worker monitoring port. Auth failures return structured JSON - see API error codes.

Tokenization settings

Use tokenization settings to enable encryption and token generation when using the PII Tokenization feature.

BLNK_TOKENIZATION_SECRET="blnk-pii-secret"

{
  "tokenization_secret": "blnk-pii-secret"
}

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

Request and payload limits

Use these settings to limit request body size and upload size.

BLNK_SERVER_MAX_REQUEST_BODY_SIZE_MB=5
BLNK_SERVER_MAX_UPLOAD_SIZE_MB=256

{
  "server": {
    "max_request_body_size_mb": 5,
    "max_upload_size_mb": 256
  }
}

	Description	Default
`BLNK_SERVER_MAX_REQUEST_BODY_SIZE_MB`	Max size in MB for JSON request bodies.	`5`
`BLNK_SERVER_MAX_UPLOAD_SIZE_MB`	Max size in MB for multipart uploads. Applies to reconciliation upload.	`256`

How limits are applied

Request type	Config key	When exceeded
JSON API requests	`BLNK_SERVER_MAX_REQUEST_BODY_SIZE_MB`	`400 Bad Request` with `GEN_MALFORMED_REQUEST` and message `"http: request body too large"`.
Multipart uploads	`BLNK_SERVER_MAX_UPLOAD_SIZE_MB`	Upload rejected.

These size limits are separate from per-endpoint item limits. A request can be within the item-count limit and still exceed the body-size limit.For example, a bulk transaction request with the accepted count may exceed 5 MB if each transaction contains large metadata or long field values.

Rate limiting

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

BLNK_RATE_LIMIT_RPS=5000000
BLNK_RATE_LIMIT_BURST=10000000
BLNK_RATE_LIMIT_CLEANUP_INTERVAL_SEC=10800

{
  "rate_limit": {
    "requests_per_second": 5000000,
    "burst": 10000000,
    "cleanup_interval_sec": 10800
  }
}

	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: Start with the defaults unless you have a clear traffic policy or abuse-prevention requirement.

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.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Server settings

`BLNK_SERVER_SECURE`

API keys

`BLNK_SERVER_SECRET_KEY`

Webhook security

Best practices

Metrics endpoint

Tokenization settings

Tokenization behaviour

Request and payload limits

How limits are applied

Rate limiting

Rate limiting behaviour

Need help?

​Server settings

​BLNK_SERVER_SECURE

API keys

​BLNK_SERVER_SECRET_KEY

Webhook security

​Best practices

​Metrics endpoint

​Tokenization settings

​Tokenization behaviour

​Request and payload limits

​How limits are applied

​Rate limiting

​Rate limiting behaviour

​Need help?

Server settings

`BLNK_SERVER_SECURE`

`BLNK_SERVER_SECRET_KEY`

Best practices

Metrics endpoint

Tokenization settings

Tokenization behaviour

Request and payload limits

How limits are applied

Rate limiting

Rate limiting behaviour

Need help?