Issue a new API key
POST/api-keys
Creates an ApiKey scoped to a subset of the platform permission catalogue and returns the plaintext ONCE (field plaintext). Store it immediately — retrieval is impossible after this call. Optional IP allow-list and rate-limit overrides are honoured by the middleware. Records api_key.create audit event. Requires the api-key:write permission.
Request
Responses
- 201
- 400
- 401
- 403
- 409
- 429
- 500
Newly-issued ApiKey record; contains the plaintext value shown only in this response.
Requested scope not in the platform catalogue or invalid payload.
Missing or invalid access token.
Caller lacks the required permission.
The request conflicts with the current state of the target resource — a duplicate unique field on registration, an idempotency-key replay with a different payload, or a webhook eventId that has already been processed. error.code may be CONFLICT or IDEMPOTENCY_CONFLICT depending on the cause.
Rate limit exceeded. Global default is 120 requests/minute per IP; auth-flow, OTP, self-registration, WebAuthn, IRA lookup, and public-lead endpoints carry tighter per-endpoint limits. Retry after the delay indicated by the Retry-After header.
Response Headers
Seconds to wait before retrying.
Unhandled server error. The response carries a meta.requestId correlator you can hand to platform operations to trace the failure through structured logs and the hash-chained audit trail. Retry with the same Idempotency-Key header if the endpoint accepts idempotency.