---
icon: 🗝️
---

# API Keys

Long-lived platform service credentials (prefixed `sk-`) for machine-to-machine API calls on behalf of a platform. Each key is 64 chars, stored only as a SHA-256 hash — the plaintext is returned once on creation and never again. Gated by `platform.plan.apiKeysEnabled` (EE/Cloud).

### Entity
`api_key`: id, platformId (FK, CASCADE), displayName, hashedValue (SHA-256, looked up every request), truncatedValue (last 4 chars for display), lastUsedAt (updated on each authenticated request).

### How it works
- Endpoints under `/v1/api-keys`, all `platformAdminOnly`: `POST` (create, returns `ApiKeyResponseWithValue` with raw value once), `GET` (list, `SeekPage` without value), `DELETE /:id`.
- Service: `add` (generates key, stores hashed/truncated), `getByValue` (lookup by SHA-256 hash, updates `lastUsedAt` — used by auth middleware), `list`, `delete`.

### Gotchas
- **A route is only reachable with an API key if its `security` lists `PrincipalType.SERVICE`.** Otherwise the key gets 403. To publish an endpoint: add `SERVICE` to its `securityAccess` call, give it `tags` and a `description` (no `hide: true`) so Fastify Swagger puts it in the OpenAPI spec, add a `docs/endpoints/<area>/<action>.mdx` page with `openapi: <METHOD> <path>`, and test it with a key. From then on its shape is a public contract. Every AI Center route (providers, tiers, capabilities, usage) is `USER`-only as of 2026-10-29, so none of it is public yet.
- Key generated with `secureApId(61)` + `sk-` prefix = 64 chars; hashed with `cryptoUtils.hashSHA256`.
- Plaintext is only ever available at creation time.

### Key files
Entry point: `apiKeyModule`, registered on the Fastify app in `packages/server/api/src/app/app.ts`.

- `packages/server/api/src/app/ee/api-keys/` — the whole backend slice: module (routes + feature gate), TypeORM entity, service
- `packages/server/api/src/app/core/security/v2/authn/` — where `getByValue` is called to authenticate an incoming key
- `packages/core/shared/src/lib/ee/api-key/` — shared `ApiKey` types and request/response contracts
- `packages/web/src/features/platform-admin/api/api-key-api.ts` — frontend API client
- `packages/web/src/features/platform-admin/hooks/api-key-hooks.ts` — React Query hooks
- `packages/web/src/app/routes/platform/security/api-keys/` — platform admin UI page and create dialog

Paths verified 2026-07-17.
