Operating

Server and Security Configuration

Configure server runtime, secure mode, request size limits, 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.

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": ""
  }
}

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

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.

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

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.

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.

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

HTTPS settings

Use these settings to serve the API over HTTPS. TLS is off by default.

BLNK_SERVER_SSL=false
BLNK_SERVER_SSL_DOMAIN=
BLNK_SERVER_SSL_EMAIL=
BLNK_CERT_STORAGE_PATH=/var/lib/blnk/certs

{
  "server": {
    "ssl": false,
    "domain": "",
    "ssl_email": "",
    "cert_storage_path": "/var/lib/blnk/certs",
    "port": "5001"
  }
}

How server.ssl works

When ssl is false, Blnk serves plaintext HTTP on server.port.

When ssl is true, Blnk:

1. Starts an HTTPS listener on the same server.port (not a separate TLS port).
2. Obtains a certificate for server.domain with Let’s Encrypt (certmagic).
3. Writes certificates to cert_storage_path.
4. Logs the scheme (https) on startup so you can confirm TLS is on.
5. Uses the same graceful shutdown path as the HTTP listener.

If a certificate cannot be issued, the server fails to start. It does not fall back to plaintext HTTP. A certificate failure names the domains in the error instead of exiting from a background goroutine.

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"
}

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.

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

How limits are applied

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

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