GET /v1/auth/api-tokens
The caller's API tokens.
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | array of ApiTokenView |
API: auth
Operations of the auth tag of the native REST API.
Browser login (decision L-113): access token in the body, rotating refresh token in the HttpOnly cookie kyv_refresh (Path=/v1/auth), CSRF double submit with the kyv_csrf cookie and the X-Kyvernon-CSRF header, Origin checks, forced password change and TOTP enrolment, API tokens. See docs/control-plane/SECURITY.md
GET
POST /v1/auth/api-tokens
Creates an API token for the caller (shown once).
Request body
application/json: CreateApiTokenRequest
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | Label (1..=64 characters). |
ttlSeconds | integer (int64) or null | Lifetime in seconds, 1 up to the controller maximum ([identity.policy] api_token_max_ttl, 365 days unless configured otherwise). Absent: the maximum. Every token expires; a longer lifetime is refused (error.api_token.ttl). |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Created | CreateApiTokenResponse |
DELETE /v1/auth/api-tokens/{id}
Revokes one of the caller's API tokens.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Id of the API token |
Responses
| Status | Description | Schema |
|---|---|---|
| 204 | Done; no body | |
| 404 | Not found (or not visible to the caller) | ErrorBody |
GET /v1/auth/config
What the sign-in page needs before anyone is signed in (no authentication).
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | AuthConfigView |
POST /v1/auth/login
Browser password login.
Request body
application/json: AuthLoginRequest
| Name | Type | Required | Description |
|---|---|---|---|
password | string | yes | Password. |
username | string | yes | Account name. |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Session (possibly restricted) or MFA challenge; token responses set the kyv_refresh and kyvernon_csrf cookies | AuthResponse |
| 401 | error.auth.invalid_credentials (same answer for every reason) | ErrorBody |
| 403 | error.auth.origin | ErrorBody |
| 429 | error.auth.rate_limited, with Retry-After | ErrorBody |
POST /v1/auth/logout
Ends the browser session (the whole token family) and clears the cookies.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Kyvernon-CSRF | header | string | yes | Value of the kyvernon_csrf cookie |
Responses
| Status | Description | Schema |
|---|---|---|
| 204 | Logged out; cookies cleared | |
| 403 | error.auth.csrf or error.auth.origin | ErrorBody |
POST /v1/auth/mfa
Second factor for a pending browser login.
Request body
application/json: AuthMfaRequest
| Name | Type | Required | Description |
|---|---|---|---|
code | string or null | Six-digit TOTP code. | |
pendingToken | string | yes | pendingToken from the login response (mfaToken is accepted as an alias). |
recoveryCode | string or null | A recovery code. |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | AuthResponse |
| 400 | neither or both of code and recoveryCode | ErrorBody |
| 401 | error.auth.invalid_code or error.auth.mfa_expired | ErrorBody |
| 429 | Rate limited; Retry-After says when to retry | ErrorBody |
POST /v1/auth/password
Changes the caller's password: every session of the account ends and the caller gets a new one (next stage: TOTP enrolment when still required).
Request body
application/json: AuthPasswordRequest
| Name | Type | Required | Description |
|---|---|---|---|
currentPassword | string | yes | Current password. |
newPassword | string | yes | New password (12..=256 characters, not common, not containing the username). |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | New session; new cookies | AuthResponse |
| 400 | error.password.* (too_short, too_long, common, repetitive, sequential, contains_username, unchanged, current_incorrect) | ErrorBody |
| 401 | Not authenticated, or the session is restricted (error.mfa_required, error.password_rotation_required) | ErrorBody |
POST /v1/auth/refresh
Rotates the refresh token and issues a new access token.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Kyvernon-CSRF | header | string | yes | Value of the kyvernon_csrf cookie |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | New tokens; new kyv_refresh cookie | AuthResponse |
| 401 | error.auth.session_expired or error.auth.refresh_reuse (cookies cleared) | ErrorBody |
| 403 | error.auth.csrf or error.auth.origin | ErrorBody |
| 409 | error.auth.refresh_race: another tab refreshed; retry once | ErrorBody |
GET /v1/auth/session
The caller's session and stage (works for restricted sessions).
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | AuthSessionView |
| 401 | Not authenticated, or the session is restricted (error.mfa_required, error.password_rotation_required) | ErrorBody |
POST /v1/auth/totp/confirm
Confirms TOTP enrolment with a current code; the session is re-keyed (new tokens and cookies) and the recovery codes are returned once.
Request body
application/json: TotpCodeRequest
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | Six-digit code. |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Authenticated; recoveryCodes present | AuthResponse |
| 401 | error.auth.invalid_code | ErrorBody |
POST /v1/auth/totp/enrol
Starts TOTP enrolment (after the password change, when TOTP is not enrolled yet).
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | TotpEnrolResponse |
| 412 | error.password_rotation_required or error.mfa.already_enrolled | ErrorBody |
POST /v1/auth/totp/recovery-codes
Replaces the caller's recovery codes (needs a current TOTP code).
Request body
application/json: TotpCodeRequest
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | Six-digit code. |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | OK | RecoveryCodesResponse |
| 401 | Not authenticated, or the session is restricted (error.mfa_required, error.password_rotation_required) | ErrorBody |
Version 0.1.