Authentication

HiveGuard has two API surfaces with different authentication methods.

Public API (/api/v1/)

Requires an API key in the X-HiveGuard-Key header.

curl -H "X-HiveGuard-Key: hg_xxxxxxxxxxxxxxxx" \
     http://localhost:8000/api/v1/health

API keys are created via the dashboard or CLI:

hiveguard keys create "my-key"

The raw key is shown once at creation. Store it immediately.

Scoping

An API key can be restricted to specific datasets. Requests using that key can only draw challenges from the allowed datasets.

401 Unauthorized

If the key is missing, invalid, or revoked:

{"detail": "Invalid or missing API key"}

Dashboard API (/dashboard/api/)

Requires HTTP Basic authentication with DASHBOARD_USERNAME and DASHBOARD_PASSWORD.

curl -u admin:changeme \
     http://localhost:8000/dashboard/api/metrics

Or as a header:

curl -H "Authorization: Basic $(echo -n admin:changeme | base64)" \
     http://localhost:8000/dashboard/api/metrics

The CLI uses HIVEGUARD_DASHBOARD_TOKEN which is the base64-encoded username:password string:

export HIVEGUARD_DASHBOARD_TOKEN=$(echo -n admin:changeme | base64)

401 Unauthorized

If credentials are missing or wrong:

{"detail": "Unauthorized"}

Error codes

Status	Meaning
200	Success
201	Created
204	No content (e.g., empty challenge pool — fail-open)
401	Missing or invalid credentials
403	Challenge failed
404	Resource not found
422	Validation error (bad request body)
503	Service unavailable (challenge pool empty, fail-closed)