API Keys

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

Scope	Permissions
`admin`	Manage API keys, manage content, presign uploads
`full`	Manage content, presign uploads, manage API keys
`upload`	Presign uploads
`playback`	Read 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"
}

Field	Type	Required	Description
`name`	string	Yes	Display name
`scope`	string	No	`admin`, `full`, `upload`, or `playback` (default: `full`)
`expiresAt`	string	No	ISO 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

Content API — register and manage content
Admin Dashboard — manage keys from the browser
Docker Setup — environment variables and deployment

Introduction

Getting Started

Server

Player

CLI

Uploader

Key Server

Serverless

Going to Production

Reference

Scopes

Bootstrap API key

First-launch setup

Create an API key

List API keys

Revoke an API key

Key format

Next steps

​Scopes

​Bootstrap API key

​First-launch setup

​Create an API key

​List API keys

​Revoke an API key

​Key format

​Next steps

Scopes

Bootstrap API key

First-launch setup

Create an API key

List API keys

Revoke an API key

Key format

Next steps