Skip to content
Cadence AI Framework

API keys

cdk_ keys, admin-only management routes, scope validation, and runtime authentication.

Intended audience: Stakeholders, Business analysts, Solution architects, Developers, Testers

Learning outcomes by role

Stakeholders

  • Explain API keys as long-lived automation credentials with scope risk.

Business analysts

  • Write stories for issuance, rotation, and revocation of cdk_ keys.

Solution architects

  • Plan storage, hashing, and encryption for keys at rest and in transit.

Developers

  • Send X-API-KEY and interpret ApiKeyTokenSession behavior.

Testers

  • Validate scope enforcement, org binding, and invalid key paths.

API keys are long-lived secrets for automation (scripts, integrations). The raw value is shown once at creation and must be stored like a password. Only trusted platform admins create keys; exercise automation with X-API-KEY. Routes live under the admin API key endpoints; persistence uses APIKeyRepository.

Summary for stakeholders

Section titled “Summary for stakeholders”
  • Risk — Keys bypass interactive MFA; scopes must mirror least privilege, and raw values are as sensitive as passwords.
  • Lifecycle — Issuance and revoke are admin operations; runtime use is a single header on each request.

Business analysis

Section titled “Business analysis”
  • Actors — Platform admins (or delegated automation accounts) create keys; integrations authenticate without an interactive user session.
  • Acceptance — Each key lists allowed cadence:* scopes; invalid or over-broad scopes are rejected at creation.

Architecture and integration

Section titled “Architecture and integration”
API key authentication flow X-API-KEY header is validated in AuthenticationMiddleware, then TenantContextMiddleware builds a synthetic session. HTTP request with X-API-KEY header AuthenticationMiddleware Hash lookup → request.state.api_key_row TenantContextMiddleware ApiKeyTokenSession + memberships; scopes via sanitize_api_key_flat_scopes

See Security and access for JWT versus API key paths and cadence.core.middleware_setup registration order in cadence.main.

Prerequisites

Section titled “Prerequisites”
  • Platform sys_admin (or equivalent) access to /api/admin/users/api-keys
  • Caller must already hold any permissions they want to embed in key scopes (no privilege escalation)

Create, list, and revoke keys

Section titled “Create, list, and revoke keys”
  • POST /api/admin/users/api-keys — Requires require_platform_sys_admin and roles_allowed(SYSTEM_API_KEYS_WRITE). Creates a key for security.user_id. Returns the raw key once in raw_key.
  • GET /api/admin/users/api-keys — Requires SYSTEM_API_KEYS_READ.
  • DELETE /api/admin/users/api-keys/{key_id} — Revokes by id for the caller’s user.

Scope validation (_validate_scopes)

Section titled “Scope validation (_validate_scopes)”

Each requested scope must:

  1. Appear in the global PERMISSIONS set.
  2. Be a permission the creating user already holds (global or in at least one org), unless the user is is_sys_admin.

Use a key at runtime

Section titled “Use a key at runtime”
  1. Send the raw secret in the X-API-KEY header (use Authorization: Bearer … only for JWTs — see Security and access).
  2. Confirm AuthenticationMiddleware resolves the row and sets request.state.api_key_row.
  3. Expect TenantContextMiddleware to build ApiKeyTokenSession with org memberships and sanitize_api_key_flat_scopes (strips dangerous permissions per the permissions module).
Section titled “Related tasks”
Security and access JWT vs API key middleware flow.
Role-based access control Permission strings and API key scope stripping.
Platform admin Other cadence:system:* routes.