Add organization API keys and an organization-scoped v1 API

[payamnj]

Organization admins can now issue scoped API keys for their own organization from a new tab on the organization page, and use them against a new /api/v1/ surface with an OpenAPI schema generated from the code that serves it.

Answers the design question from the discussion that preceded this: one model, expanded — not a second model.

One model, or two?

Platform and organization keys share ~90% of their machinery: generation, verification, expiry, revocation, listing, rate limiting, last_used_at. Splitting them means writing that twice and fixing every crypto bug twice. The scope of what a key may do is authorization data, not a reason for a separate table.

The one real argument for two models was avoiding a fail-open — if "platform key" is encoded as organization IS NULL, any bug that drops the org filter silently yields a global-privilege key. So it isn't encoded that way. An explicit key_type column, plus a CheckConstraint tying it to the presence of an organization, makes the platform check key_type == PLATFORM: an affirmative assertion a forgotten filter can't accidentally satisfy, and the DB refuses to store an incoherent row.

Dropping the JWT and the reversible encryption

The JWT was signed with a fixed exp of datetime.max and carried no claim that wasn't already the credential. Its only real function was smuggling the row's salt so verification could narrow the "decrypt every candidate row and compare plaintext" lookup — a lookup index wearing a security costume.

Keys are now a SHA-256 hash of a 256-bit random secret. Token format is elk_<key_id>_<secret>, where key_id is a non-secret public identifier making verification a single indexed lookup. Plain SHA-256 rather than a slow KDF: the secret is 256 bits of randomness, not a human password, so stretching would only add latency to every request.

Handing an org admin a self-issued credential is a much wider exposure than one internal platform key, so "we can decrypt every customer's API key from the database" isn't a property to carry forward.

Upgrade path

Existing keys keep working. A data migration derives key_id/secret_hash from the stored ciphertext, and legacy JWTs resolve through the same hash — both formats converge on one code path. Verified end-to-end against a database seeded at 0016 with a real Fernet-encrypted key, migrated forward: the legacy JWT still authenticates and the key/salt columns are gone.

Keys can no longer be read back (breaking). Both key screens now show key_id and status rather than the key itself; the token appears once, in a dialog at creation. An operator who lost a key issues a replacement. A key whose ciphertext won't decrypt (rotated ENCRYPTION_SECRET_KEY) gets a hash no token can match — fail closed rather than deleting the row, which would silently widen access if that key was the only thing gating an endpoint.

The v1 API

One endpoint: POST /api/v1/enrollments/, requiring the enrollments:create scope. Mounted separately from /api/public/, which is the unauthenticated embed-token surface for third-party pages — bolting an authenticated partner API onto it would get the two trust models confused.

The organization comes from the key, never from the URL or body; a slug belonging to another organization reads as 404 rather than 403, so a key holder can't probe which other organizations exist. Rate limiting is keyed on key_id rather than client IP, since a server-to-server caller may sit behind a shared egress address.

Organization keys must carry at least one scope — enforced in clean() rather than as a DB constraint, since unlike the key_type constraint this one fails closed (a scopeless key authenticates and can then do nothing), so a backstop below the model buys hygiene rather than safety.

Managing keys

A new API Keys tab on the organization page, after Newsletters. The table follows the platform API keys screen — key id, status, created by, created at, last used — plus the scopes each key carries. The scope checkboxes come from ApiKeyScope through the page context rather than being listed again in the frontend, so the form can't offer a scope the API would reject, and a new scope appears with no frontend change.

Two controls, with two jobs:

• PlatformFeature.ORGANIZATION_API (present by default) decides whether the UI offers the tab.
• can_create_organization_api_key(request, organization) and can_delete_organization_api_key(request, organization) decide what the API allows. Both default to True and reject with 403 before any database work, following the existing can_create_course hook pattern. They take the resolved Organization rather than an id, so a plan-limit check needs no second query.

The delete hook runs before the key lookup, so a caller who may not revoke can't distinguish a real key id from a made-up one by comparing 403 against 404.

OpenAPI schema

GET /api/v1/openapi.json serves an OpenAPI 3.1 document, validated against openapi-spec-validator as a one-off. No new dependency — django-ninja was considered and rejected for now: it's a view-layer commitment, and forcing it on every consumer of a library with six runtime dependencies is a real imposition (namespace collisions with consumers running their own NinjaAPI, and coupling this library's Django support window to ninja's).

Three things are read from the implementation rather than restated:

• Paths from the routed URLconf, including the mount prefix — so they follow wherever a consuming project mounts the app
• Schemas from the Pydantic models the views validate with; Pydantic v2 emits JSON Schema 2020-12, which is what OpenAPI 3.1 consumes
• Security from the scopes the auth decorator enforces, which it now publishes — so the documented scope is the checked scope

Two tests do the real work: one fails the build if a routed endpoint has no spec, and a second monkeypatches the spec away to prove that guard actually fires.

Not included

• No rendered docs page. The JSON is what tooling consumes; point Swagger UI, Redoc or Postman at it.
• No "skip verification" flag on enrollment. A partner enrolling from its own signup flow arguably has consent already, but adding a way to put someone on an email course without confirming the address is a deliberate policy call, not something to slip into a new API. Easy to add later; breaking to remove.

Testing

1094 backend + 379 frontend tests pass. New coverage: model constraints and token round-tripping, legacy JWT back-compat, scope enforcement, cross-org isolation, expiry/revocation, both key types rejected from each other's surface, per-key rate limiting, the OpenAPI generator, the permission hooks (including the no-leak ordering on delete), and the tab's create/revoke flows and feature gating.

🤖 Generated with Claude Code