VerdifaX

Authentication

Verdifax authenticates API callers via a single header. Keys are provisioned out-of-band and shown to the operator exactly once.

X-Verdifax-Key: vfx_<24-byte-random-hex>

Every authenticated endpoint accepts the same header. /health is public.

Two modes

Open mode, when no API keys exist in the database (a fresh deploy, before any key has been provisioned), every authenticated endpoint admits the caller as anonymous (api_key_id = 0). This keeps the docker quickstart trivial.

Locked mode, once any key exists, the API server enforces the header. Calls without a valid X-Verdifax-Key get 401. Run history is scoped to the key that produced it: /runs only returns runs owned by the calling key, and /runs/{id} 404s if the key didn't own that run.

Provisioning a key

curl -s -X POST http://localhost:9090/admin/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"compliance-team-2026"}' | python3 -m json.tool

{
  "ok": true,
  "id": 1,
  "name": "compliance-team-2026",
  "secret": "vfx_a1b2c3d4...",
  "hint": "Store this secret now, it will never be shown again."
}

The server stores only sha256(secret). Lose the secret and you must revoke + reissue.

Listing keys

curl -s http://localhost:9090/admin/keys \
  -H "X-Verdifax-Key: vfx_..." | python3 -m json.tool

Returns names, creation timestamps, last-used timestamps, run counts, and revocation status, never the secrets.

Revoking a key

curl -s -X DELETE http://localhost:9090/admin/keys/1 \
  -H "X-Verdifax-Key: vfx_..."

Revocation is immediate. Subsequent calls with that key get 401.

Rate limiting

Every authenticated endpoint is rate-limited at 100 requests/minute per key by default (configurable via --rate-limit). Anonymous callers in open mode are limited per remote address.

Continue