aegis-api-token-security
Scope & Objectives
Audit every stage of the token lifecycle for one internet-exposed HTTP API that authenticates machine clients with opaque bearer/API tokens (strings presented as Authorization: Bearer <token> or an API-key header). Ten domains, in priority order:
- Design — entropy floor (>=128 bits from a CSPRNG), format conventions (type prefix, checksum), forbidden token bases.
- Server-side storage — the classic fatal flaw: plaintext or reversibly encrypted tokens in the database versus store-the-hash-only.
- Transport — TLS-only enforcement, header versus query-string versus cookie carriage.
- Scoping & privilege model — god-tokens versus scoped, tenant-bound, read/write-separated keys.
- Expiry & rotation — lifetime policy, downtime-free rotation with overlap windows, stale-token reaping.
- Revocation & incident readiness — revocation latency including cached-auth gaps, leak-response runbook.
- Rate limiting & abuse controls — per-key quotas, 429 semantics, unauthenticated-endpoint separation.
- Key-enumeration resistance — uniform timing/error behavior on invalid tokens.
- Logging & monitoring — safe fields, never-log-full-token rule, anomaly alerting.
- Client hygiene & host sprawl — distribution guidance, and where tokens hide on the host (bridge to HSECRET).
Out of scope (cross-references): JWT structure, algorithms, none/weak-secret validation → AUTHN (skills/code/authn-session/SKILL.md); CSRF consequences of cookie-carried credentials → WEB (skills/code/web-client/SKILL.md); general API abuse, pagination/enumeration, unauthenticated-endpoint hardening → API (skills/code/api-security/SKILL.md); TLS termination and header stripping at the edge → TLS (skills/server/tls-proxy/SKILL.md); secret contents in files/repos → SECRETS (skills/code/secrets-data-exposure/SKILL.md); volumetric thresholds → DoS (skills/code/denial-of-service/SKILL.md). Where this playbook names a logging-monitoring module, apply its alert-routing guidance when that module exists in your copy.
Operating rules: