Skip to main content
The BlindCast Server uses API keys to authenticate management requests. Keys are SHA-256 hashed before storage — the raw key is only shown once at creation time.

​
Scopes

ScopePermissions
adminManage API keys, manage content, presign uploads
fullManage content, presign uploads, manage API keys
uploadPresign uploads
playbackRead content only
Only admin and full scopes can create, list, or revoke API keys.

​
Bootstrap API key

For automated deployments, set the ADMIN_API_KEY environment variable: 
ADMIN_API_KEY=bk_your_bootstrap_key
This key is accepted as an admin-scope key without being stored in the database. It lets you make the first API call to create a proper stored key.

​
First-launch setup

If no API keys exist and ADMIN_API_KEY is not set, use the setup endpoint: 
curl -X POST http://localhost:4100/api/v1/setup \
  -H "Content-Type: application/json" \
  -d '{"name": "Admin Key"}'
Response (201): 
{
  "api_key": { "id": "...", "name": "Admin Key", "scope": "admin", "..." : "..." },
  "raw_key": "bk_a1b2c3d4..."
}
The setup endpoint only works once — it returns 409 if any API keys already exist. Store the raw_key immediately; it cannot be retrieved again.
The admin dashboard at /admin guides you through this process with a setup wizard.

​
Create an API key

POST /api/v1/api-keys
Authorization: Bearer bk_your_admin_key

{
  "name": "Upload Service",
  "scope": "upload",
  "expiresAt": "2026-12-31T00:00:00Z"
}
FieldTypeRequiredDescription
namestringYesDisplay name
scopestringNoadmin, full, upload, or playback (default: full)
expiresAtstringNoISO 8601 expiry date
Response (201): 
{
  "api_key": {
    "id": "uuid-...",
    "name": "Upload Service",
    "keyPrefix": "bk_a1b2...",
    "scope": "upload",
    "expiresAt": "2026-12-31T00:00:00.000Z",
    "revokedAt": null,
    "createdAt": "2026-03-02T12:00:00.000Z"
  },
  "raw_key": "bk_a1b2c3d4e5f6..."
}
Save the raw_key — it is only returned once. The stored keyPrefix shows the first few characters for identification.

​
List API keys

GET /api/v1/api-keys
Authorization: Bearer bk_your_admin_key
Response (200): 
{
  "api_keys": [
    {
      "id": "uuid-...",
      "name": "Upload Service",
      "keyPrefix": "bk_a1b2...",
      "scope": "upload",
      "lastUsedAt": "2026-03-02T12:00:00.000Z",
      "expiresAt": "2026-12-31T00:00:00.000Z",
      "revokedAt": null,
      "createdAt": "2026-03-02T12:00:00.000Z"
    }
  ]
}
Raw keys are never returned — only the prefix is shown.

​
Revoke an API key

DELETE /api/v1/api-keys/:id
Authorization: Bearer bk_your_admin_key
Response (200): The revoked key object with a revokedAt timestamp. Revoked keys are rejected on all subsequent requests.

​
Key format

API keys use the format bk_ followed by 64 hex characters (32 random bytes): 
bk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1
The bk_ prefix makes keys easy to identify in logs and configuration.

​
Next steps