API: ApiKeys
Project write-key management (issue, rotate, revoke).
На этой странице
Раздел собран из спецификации OpenAPI продукта: 4 метод(ов). Поверхность — query-api (основной API, база /api/v1). Все методы требуют аутентификации.
Методы раздела
/projects/{id}/keys List a project's bounded ingest credentials (admin+)
Параметры
| Имя | Где | Тип | Описание |
|---|---|---|---|
id обязателен | Путь | integer (int32) | Project id. |
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 200 | Credential metadata only. Full values and hashes are never returned; `key` exists only in create/rotate responses. | object |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
| 403 | Authenticated but not permitted (code=forbidden) | Error |
| 404 | Resource not found (code=not_found) | Error |
/projects/{id}/keys Issue a public browser or secret server credential (admin+)
A JSON body must select `browser` or `server`; empty bodies and `credential_kind=legacy` are rejected. Existing `pp_wk` credentials remain usable during the documented migration window and may be rotated only as a same-profile emergency migration operation. Browser credentials require exact origins, receive a 90-day expiry and `signup_completed` event allowlist by default, and are public project-scoped tokens rather than secrets. Server `pp_sk` values are secret, shown once and must stay in a backend secret manager.
Параметры
| Имя | Где | Тип | Описание |
|---|---|---|---|
id обязателен | Путь | integer (int32) | Project id. |
Тело запроса application/json , обязательно
| Поле | Тип | Описание |
|---|---|---|
credential_kind обязательно | enum(browser, server) | Kinds accepted for new issuance. Legacy `pp_wk` is deliberately absent: existing legacy credentials are migration-only and may only be rotated without changing their profile. |
scopes необязательно | array<enum(config:read, events:write, identity:identify, identity:alias, replay:write, picker:capture)> | Optional bounded subset for the selected kind. Empty/omitted uses the kind's defaults. Browser excludes identity:alias; server allows only events:write, identity:identify and identity:alias. |
allowed_origins необязательно | array<string (uri)> | Required only for browser credentials. Exact canonical scheme/host/port Origins; paths, queries, fragments, userinfo and wildcard values are rejected. This is defense in depth, not proof that an event is authentic. |
expires_at необязательно | string (date-time) | Optional future expiry. Browser credentials default to 90 days. |
browser_event_allowlist необязательно | array<string> | Browser-only exact custom event names. Empty/omitted defaults to `signup_completed`; ActionPulse-managed `pp.*` names are rejected. |
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 201 | Created credential (full `key` returned once) | IssuedApiKey |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
| 403 | Authenticated but not permitted (code=forbidden) | Error |
| 404 | Resource not found (code=not_found) | Error |
| 409 | Demo project — ingest keys are not available (code `demo_project`) | Error |
| 422 | Missing body, legacy/new unsupported kind, invalid scope, origin, expiry, allowlist or unknown JSON field. | Error |
/projects/{id}/keys/{kid}/revoke Revoke an ingest credential (admin+)
Параметры
| Имя | Где | Тип | Описание |
|---|---|---|---|
id обязателен | Путь | integer (int32) | Project id. |
kid обязателен | Путь | integer (int64) | API key id. |
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 204 | Revoked | пусто |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
| 403 | Authenticated but not permitted (code=forbidden) | Error |
| 404 | Resource not found (code=not_found) | Error |
/projects/{id}/keys/{kid}/rotate Revoke a credential and issue a same-profile replacement (admin+)
The request body must be empty. Rotation preserves credential kind, scopes, origins, expiry and browser event allowlist; it cannot be used to elevate a profile. An expired credential must be replaced explicitly rather than rotated. Rotation of an existing legacy `pp_wk` remains available only as a migration-safety exception; the create endpoint cannot issue a new legacy credential.
Параметры
| Имя | Где | Тип | Описание |
|---|---|---|---|
id обязателен | Путь | integer (int32) | Project id. |
kid обязателен | Путь | integer (int64) | API key id. |
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 200 | New same-profile credential (full `key` returned once) | IssuedApiKey |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
| 403 | Authenticated but not permitted (code=forbidden) | Error |
| 404 | Resource not found (code=not_found) | Error |
| 409 | Demo project — ingest keys are not available (code `demo_project`) | Error |
| 422 | Non-empty request body or expired credential. | Error |
Источник раздела — docs/api/openapi.yaml репозитория продукта,
версия API 1.0.0, OpenAPI 3.0.3,
снимок 095579325c2d.
Расхождение снимка со спецификацией роняет сборку документации.