docs(api-keys): capability-based scope vocabulary (ADR-049)

[alexgarden-mnemom]

Summary

Closes the doc/code drift surfaced by T1-4 deploy-gate closeout: the docs previously said scopes were "Owner / Admin / Member" while the code shipped "gateway / api". Both sides now agree on the capability-based vocabulary defined in ADR-049: `gateway`, `api:read`, `api:write`, `admin:org`, `admin:platform`.

Changes

`guides/api-keys.mdx` — full rewrite of the scope section

• Per-scope reference table: what each scope grants, who can mint it.
• Scope semantics: capabilities are independent (admin scopes don't imply api:read); mint-time ceiling enforced server-side; request-time role re-check on every admin-scope use; demotion semantics (admin keys lose admin power immediately on role change without rotation, but still authenticate for non-admin endpoints).
• "Picking scopes for common patterns" — concrete recipes (local dev, CI without mutations, read-only analytics, service-account org admin, Mnemom-internal automation).
• Legacy keys section: documents the auto-alias (`['gateway', 'api']` → `['gateway', 'api:read', 'api:write']` at request time), migration path, and dashboard rendering.
• Hygiene checklist updated: smaller blast radius via least scope, prefer `api:read` for analytics, treat admin-scope keys with extra care.

`guides/authentication.mdx` — auth-flow summary alignment

• Replaces the "Owner / Admin / Member" copy at line ~101 with the capability-based vocabulary table.
• Cross-links to the api-keys.mdx deep dive.
• Documents the legacy-key path with link.

`api-reference/openapi.json` — schema + endpoint updates

• New `ApiKeyScope` schema component: closed enum for the canonical scopes plus legacy `api` for backward compatibility. Description includes the per-scope semantics and a link to the guide.
• `ApiKey.scopes` now references the enum; the field description points to the guide and notes the default scope set.
• `POST /v1/api-keys` request body declares the `scopes` parameter with the canonical default `["gateway", "api:read", "api:write"]` and a description of the mint-time ceiling behavior.
• `POST /v1/orgs/{org_id}/api-keys` request body declares `scopes` with the same default and notes that `admin:org` is implicit-eligible (the route already verifies owner/admin).
• 400 / 403 responses documented for unknown scope names and mint-time ceiling rejections respectively.

What this enables

• Customers reading the API reference now see the actual scope vocabulary the code accepts (no more "Owner/Admin/Member" surprise).
• The OpenAPI enum makes generated SDKs in any language correctly type-check the scope set.
• Per-scope migration guidance is concrete instead of aspirational.
• SOC 2 / compliance attestation surface is honest: the audit trail of "what each key was authorized to do" matches what's documented.

Test plan

• CI green (drift check, openapi-drift-check.yml)
• Mintlify build of `guides/api-keys.mdx` and `guides/authentication.mdx` renders cleanly
• Per-endpoint pages (`api-reference/endpoint/post-api-keys.mdx` etc.) automatically reflect the new openapi.json content
• Cross-links resolve

Refs

• ADR-049 (mnemom/scale)
• mnemom-api#351 (auth gates), mnemom-api#352 (legacy alias)
• mnemom-website#364 (sibling scope-picker UI)
• safe-house-hardening T1-4 (work that surfaced this drift)

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Mnemom	🟢 Ready	View Preview	May 8, 2026, 3:35 AM