Configuration

The key server is configured entirely via environment variables. No config files needed.

Required variables

Variable	Description
`MASTER_KEY_HEX`	Master key as hex string (64 chars = 32 bytes). From `blindcast keygen`.
`SALT_HEX`	Salt as hex string (64 chars = 32 bytes). From `blindcast keygen`.
`CORS_ORIGINS`	Allowed CORS origin. Must match your app’s domain exactly (e.g., `https://app.example.com`).

Never set CORS_ORIGINS=* in production. The key server sends Access-Control-Allow-Origin with the exact matching origin and includes Vary: Origin for correct caching.

Authentication

Set one of these to enable JWT validation on key requests. If neither is set, the key server runs in development mode with no authentication.

Variable	Description
`AUTH_JWT_SECRET`	Base64-encoded shared secret for HS256 JWT validation
`AUTH_JWKS_URL`	URL to a JWKS endpoint for RS256/ES256 validation (e.g., `https://auth.example.com/.well-known/jwks.json`)

If both are set, AUTH_JWKS_URL takes precedence.

How auth works

The player sends Authorization: Bearer <token> on every key request
The key server validates the JWT signature
If valid, the key is derived and returned
If invalid or expired, the server returns 401 Unauthorized

# Example: Auth0
docker run -d \
  -e MASTER_KEY_HEX=... \
  -e SALT_HEX=... \
  -e CORS_ORIGINS=https://app.example.com \
  -e AUTH_JWKS_URL=https://your-tenant.auth0.com/.well-known/jwks.json \
  -p 4100:4100 \
  blindcast/keyserver

Optional variables

Variable	Default	Description
`PORT`	`4100`	Port to listen on
`ENABLE_PRESIGN`	`false`	Enable the presign endpoint for browser uploads
`S3_BUCKET`	—	S3 bucket for presigned URLs (required if presign is enabled)
`S3_REGION`	`us-east-1`	AWS region
`AWS_ACCESS_KEY_ID`	—	AWS credentials (for presign)
`AWS_SECRET_ACCESS_KEY`	—	AWS credentials (for presign)
`DATABASE_URL`	`sqlite:///data/blindcast.db`	Database URL for lease storage
`LEASE_TTL_MS`	`300000` (5 min)	Default lease TTL in milliseconds

Docker volumes

Path	Purpose
`/data`	SQLite database file (persist across restarts)

docker run -d \
  -v blindcast-data:/data \
  -e MASTER_KEY_HEX=... \
  -e SALT_HEX=... \
  -e CORS_ORIGINS=https://app.example.com \
  -p 4100:4100 \
  blindcast/keyserver

Health check

GET /health returns 200 OK with { "status": "ok" }. Use this for Docker health checks and load balancer probes.

curl http://localhost:4100/health
# {"status":"ok"}

Introduction

Getting Started

Server

Player

CLI

Uploader

Key Server

Serverless

Going to Production

Reference

Required variables

Authentication

How auth works

Optional variables

Docker volumes

Health check

​Required variables

​Authentication

​How auth works

​Optional variables

​Docker volumes

​Health check

Required variables

Authentication

How auth works

Optional variables

Docker volumes

Health check