API Key Architecture (Explanation)

Last Updated: 2026-02-04
Content-Type: Explanation
Audience: Developers

---

Goals

• Compatibility: Support OpenAI-style clients and “standard” API key headers.
• Security: Never store plaintext secrets; allow only one-time reveal.
• Operability: Admin can revoke/rotate keys; keys have scopes and optional expiry.

How keys work

• Keys are issued as copy/paste-friendly strings (example prefix: kira_sk_...).
• The database stores:
  • keyPrefix (first 12 chars) for lookup
  • keyHash (bcrypt) for validation
  • secretCiphertext/iv/tag (AES-256-GCM) until the user reveals once

After reveal:

• The encrypted secret fields are cleared
• secretRevealedAt is set

Authentication flow

1. Request arrives with either X-API-Key or Authorization: Bearer ...
2. If the Bearer token looks like a JWT, JWT auth handles it
3. Otherwise, API key auth:
   • loads by keyPrefix
   • bcrypt-compares full secret to keyHash
   • attaches req.apiKey and req.user

OpenAI-compatible routing

Kirakira mounts OpenAI-compatible routes at /v1/* and reuses the same internal interaction pipeline as the Portal.