Authentication

API Key Format

Every tenant receives a key in the format:

ack_live_a1b2c3d4e5f6789012345678901234567890123456789

Pass the key in the X-Citadel-Key header on every request:

curl -H "X-Citadel-Key: ack_live_YOUR_KEY" \
     https://api.aethercitadel.cloud/v1/intent/generate

Never put your API key in URLs, query parameters, or client-side JavaScript. It belongs in a server-side environment variable only.

Property	Detail
Transmission	HTTPS only — TLS 1.3 enforced
Comparison	Constant-time (`subtle::ConstantTimeEq`) — timing attacks impossible
Storage	Stored as plaintext in your tenant record — rotate if compromised
Rate limit	Per-plan monthly verification limit (not per-second)

If your key is exposed, generate a new one immediately. The old key is invalidated the moment you rotate.

curl -X POST https://api.aethercitadel.cloud/v1/tenant/rotate-key \
  -H "X-Citadel-Key: ack_live_YOUR_CURRENT_KEY"

{
  "new_key": "ack_live_newkeyhere...",
  "message": "Your old key is now invalid. Update your integration immediately."
}

Update all your services before rotating. Once rotated, the old key returns 401 on every request.

When you exceed your limit, requests return 429 Too Many Requests. Upgrade your plan to restore access.

Key Type	Used By	Auth Header
Admin key (`CITADEL_API_KEY`)	Internal services (AetherScale, AetherDB)	`X-Citadel-Key`
Tenant key (`ack_live_xxx`)	Your paid customers	`X-Citadel-Key`

Both key types use the same header. The server validates them through the same constant-time comparison.