Authentication

BVE Gateway uses two separate authentication schemes — one for public API access and one for admin operations.

Public API keys

Public API keys authenticate requests to /v1/* endpoints.

Format: sk-bve- followed by 64 lowercase hex characters.

Example: sk-bve-a1b2c3d4e5f6... (71 characters total)

Keys are provisioned by an admin via POST /admin/api-keys and are only shown once at creation time. They are never stored in plain text — only sha256(key + pepper) is stored in D1.

How to pass your key

Use the Authorization header with the Bearer scheme:

Authorization: Bearer sk-bve-YOUR_KEY

Auth errors

Code	Status	Meaning
`missing_api_key`	401	No `Authorization` header
`invalid_api_key`	401	Header is not `Bearer`, key lacks `sk-bve-` prefix, or key not found in DB
`api_key_suspended`	403	Key exists but is suspended
`api_key_revoked`	403	Key has been revoked

All error responses use the OpenAI error format.

Key statuses

Status	Can make requests
`active`	Yes
`suspended`	No (403)
`revoked`	No (403)

Admin key

Admin routes (/admin/*) require the ADMIN_API_KEY secret set in the Worker environment.

Format: Any string — set by the operator.

Convention: Use a long random string (not the sk-bve- format).

Example placeholder: admin_bve_YOUR_ADMIN_KEY

Pass it the same way as a public key:

Authorization: Bearer admin_bve_YOUR_ADMIN_KEY

The admin auth middleware also accepts the token without the Bearer prefix, but using the full Bearer scheme is recommended.

CORS

BVE Gateway allows cross-origin requests from any origin (*). The following headers are allowed:

Authorization
Content-Type
X-Request-Id

The X-Request-Id response header is exposed to browsers. Preflight cache is 24 hours.