Stable API tag

auth

Authentication, sessions, and setup

30 paths · 35 operations

/v1/account/password

post

Change your password and revoke your other sign-ins; requires the current password and a human session

Operation ID: changeOwnPassword
Authentication: Bearer token
Request body: Present · required

Parameters: none declared.

Response codes

204 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/browser-session

get

Restore cookie session metadata

Operation ID: getBrowserSession
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

post

Rotate a legacy bearer into a cookie without extending expiry

Operation ID: migrateBrowserSession
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/capabilities

post

Project the CALLING credential's authority over registered operations

Operation ID: authCapabilities
Authentication: Bearer token
Request body: Present · required

Parameters
Name	In	Required	Type
X-Olivares-Tenant	header	no	string · uuid

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/effective-rights

get

One trustee's effective rights over one node: the subject, the node, the assurance the answer holds, the lineage path and each right's state. Needs authz:admin; answers 404 while the operator has the AuthZEN search surface disabled and 403 outside its permitted network

Operation ID: getEffectiveRights
Authentication: Bearer token
Request body: None

Parameters
Name	In	Required	Type
X-Olivares-Tenant	header	no	string · uuid
subject_type	query	yes	string
subject_id	query	yes	string · uuid
kind	query	yes	string
id	query	yes	string · uuid

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/login

post

Exchange email/password for a session token

Operation ID: login
Authentication: No authentication
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/logout

post

Revoke the calling session

Operation ID: logout
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

204 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/os-account-bindings

post

Start an OS-account binding under the current administrator's user authorization and configured step-up; direct TLS required.

Operation ID: beginOSAccountBinding
Authentication: Bearer token
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/os-account-bindings/complete

post

Complete from the subject's own session with fresh native PAM authentication and Account validation; direct TLS required. Returns public mapping metadata only.

Operation ID: completeOSAccountBinding
Authentication: Bearer token
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/os-account-bindings/{id}

get

Read administrative mapping metadata and its audit digest; direct TLS and current administrative step-up required.

Operation ID: getOSAccountBinding
Authentication: Bearer token
Request body: None

Parameters
Name	In	Required	Type
id	path	yes	string · uuid
X-Olivares-Tenant	header	no	string · uuid

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

delete

Revoke current authority while permanently retaining the immutable account/UID/subject reservation; direct TLS and current administrative step-up required.

Operation ID: revokeOSAccountBinding
Authentication: Bearer token
Request body: None

Parameters
Name	In	Required	Type
id	path	yes	string · uuid
X-Olivares-Tenant	header	no	string · uuid

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/piv/elevate

post

Verify the presented PIV certificate (chain, OCSP, user binding) and elevate the calling session to AAL3 (method piv)

Operation ID: elevatePIV
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/piv/status

get

The calling session's presented PIV smart-card certificate status (501 when no PIV verifier roots are configured)

Operation ID: getPIVStatus
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/refresh

post

Renew the calling session token (rotates the credential, extends expiry)

Operation ID: refreshToken
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/step-up-policy

get

Read what administrative actions demand beyond the sign-in

Operation ID: getStepUpPolicy
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

put

Set what administrative actions demand beyond the sign-in

Operation ID: setStepUpPolicy
Authentication: Bearer token
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/totp

delete

Remove the calling account's factor behind the administrative step-up

Operation ID: removeTOTP
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/totp/activate

post

Prove possession and reveal recovery codes once

Operation ID: activateTOTP
Authentication: No authentication
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/totp/challenge

post

Complete a pending login with a code or recovery code

Operation ID: completeTOTPLogin
Authentication: No authentication
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/totp/enrol

post

Start a TOTP enrolment with a session or a pending login

Operation ID: enrolTOTP
Authentication: No authentication
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/totp/policy

get

Read the administrator factor policy

Operation ID: getTOTPPolicy
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

put

Set the administrator factor policy behind the administrative step-up

Operation ID: setTOTPPolicy
Authentication: Bearer token
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/totp/status

get

Read the calling account's factor status

Operation ID: getTOTPStatus
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/auth/webauthn/authenticate

post

Verify the browser's assertion and elevate the calling session to AAL3

Operation ID: webauthnAuthenticate
Authentication: Bearer token
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/webauthn/authenticate/options

post

Issue WebAuthn assertion options (challenge) for a step-up of the calling session

Operation ID: webauthnAuthenticateOptions
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/webauthn/credentials

get

The calling user's registered authenticators — id, label and registration time only, never key material

Operation ID: listWebAuthnCredentials
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/webauthn/credentials/{id}

delete

Unregister one of the calling user's authenticators (lost/stolen-key remediation; step-up required)

Operation ID: deleteWebAuthnCredential
Authentication: Bearer token
Request body: None

Parameters
Name	In	Required	Type
id	path	yes	string · uuid

Response codes

204 · 400 · 401 · 403 · 404 · 409 · 429

patch

Update the display name of one of the calling user's authenticators (owner-only, no step-up: a metadata change)

Operation ID: renameWebAuthnCredential
Authentication: Bearer token
Request body: Present · required

Parameters
Name	In	Required	Type
id	path	yes	string · uuid

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/webauthn/register

post

Verify the browser's attestation and persist the credential (403 on any ceremony failure, 409 on an already-registered credential id)

Operation ID: webauthnRegister
Authentication: Bearer token
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/webauthn/register/options

post

Issue WebAuthn creation options (challenge) to register a new authenticator for the calling session's user

Operation ID: webauthnRegisterOptions
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/auth/whoami

get

The calling principal and its tenant grants

Operation ID: whoami
Authentication: Bearer token
Request body: None

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/invites/accept

post

Redeem an invitation token: set the password, activate the account and mint a session (the single-use token is the gate; no authentication)

Operation ID: acceptInvite
Authentication: No authentication
Request body: Present · required

Parameters: none declared.

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429

/v1/setup

post

Create the first organization and the superadmin that owns it, with the one-time setup token

Operation ID: setupFirstAdmin
Authentication: No authentication
Request body: Present · required

Parameters: none declared.

Response codes

201 · 400 · 401 · 403 · 404 · 409 · 429

/v1/users/{id}/totp

get

Read a member's factor status in the selected tenant

Operation ID: getUserTOTPStatus
Authentication: Bearer token
Request body: None

Parameters
Name	In	Required	Type
id	path	yes	string · uuid
X-Olivares-Tenant	header	no	string · uuid

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503

/v1/users/{id}/totp/reset

post

Reset a tenant-governed member's factor behind the administrative step-up

Operation ID: resetUserTOTP
Authentication: Bearer token
Request body: None

Parameters
Name	In	Required	Type
id	path	yes	string · uuid
X-Olivares-Tenant	header	no	string · uuid

Response codes

200 · 400 · 401 · 403 · 404 · 409 · 429 · 503