Authentication

Bearer token

All routes under /api/v1 require an Authorization: Bearer header whose value matches the Worker secret API_BEARER_TOKEN. Set it in production with:

wrangler secret put API_BEARER_TOKEN

Pass the token in every request:

curl -sS \
  -H "Authorization: Bearer <API_BEARER_TOKEN>" \
  https://<your-worker-host>/api/v1/

Missing or invalid tokens return 401 { "error": "Unauthorized" }. The comparison is constant-time to prevent timing attacks.

Health check

GET /api/v1 (no trailing slash) returns a JSON status object. The Bearer token is still required because the middleware applies to the entire /api/v1 tree.

curl -sS \
  -H "Authorization: Bearer <API_BEARER_TOKEN>" \
  https://<your-worker-host>/api/v1

Response:

{ "status": "ok", "version": "v1" }

Local development

For local development with wrangler dev, copy .dev.vars.example to .dev.vars and set a value for API_BEARER_TOKEN. The file is gitignored.

# .dev.vars
API_BEARER_TOKEN=change-me-to-a-long-random-string

Use a long random value that matches whatever token your local REST client sends.

Admin UI

The HTML admin at /admin does not use Bearer tokens — it is served as HTML form pages. In production, protect /admin with Cloudflare Zero Trust Access.

Browsing any /api/v1/* endpoint without a Bearer header shows this documentation. REST clients that include the header receive JSON.