Signing in
Sessions, and local password accounts (KAIROS-I-0018). /api/login and /api/local-accounts are only on a deployment with KAIROS_LOCAL_AUTH on. /api/session and /api/logout are on each deployment (KAIROS-T-0364). /api/login and /api/logout are unauthenticated by nature. Everything under /api/local-accounts is org-admin only, including the reads: a list of somebody’s live sessions is a security surface rather than work content.
POST /api/login
Section titled “POST /api/login”POST /api/login — exchange an email and a password for a session bearer.
Present the returned token as Authorization: Bearer <token>. It is returned
exactly once; only its hash is stored. Failed attempts are throttled per account
and per source address.
The response also sets the session as the cookie kairos_session: HttpOnly,
Secure, SameSite=Strict, Path=/, for the lifetime of the session. The GUI
uses the cookie, so a reload keeps the session. A request with the cookie and no
bearer that changes something must come from the Kairos page (its Origin).
Request body (required): application/json, LoginRequest
| Response | Body | Meaning |
|---|---|---|
200 |
LoginResponse |
A session bearer |
401 |
— | Incorrect email or password |
429 |
— | Too many failed attempts |
POST /api/logout
Section titled “POST /api/logout”POST /api/logout — revoke the presented session, and clear the session cookie.
The session is the bearer, or else the cookie kairos_session. A logout with the
cookie must come from the Kairos page (its Origin).
Outside the auth stack, and 204 whatever happens: a caller logging out with a token that has already expired has got what they wanted, and telling them the token was no good would be both useless and an oracle.
| Response | Body | Meaning |
|---|---|---|
204 |
— | The session is revoked, or was not one |
POST /api/session
Section titled “POST /api/session”POST /api/session — open a session from a sign-in with the identity provider.
Send the OIDC token of the sign-in as Authorization: Bearer <token>. The
response is the same as the response of POST /api/login. The body has a
session bearer, and the cookie kairos_session has the session too. Thus a
reload of the GUI keeps the session, also when the identity provider gives no
refresh token. The session lasts KAIROS_SESSION_TTL_SECS, or until a logout or
an admin revokes it.
Only an OIDC bearer opens a session. The server refuses the cookie alone, a session bearer and an API key.
| Response | Body | Meaning |
|---|---|---|
200 |
LoginResponse |
A session bearer |
401 |
— | No valid credential |
403 |
— | The credential is not an OIDC bearer |
local-accounts
Section titled “local-accounts”POST /api/local-accounts
Section titled “POST /api/local-accounts”POST /api/local-accounts — create a local account (or add a password to an
existing person) and make them a member of this organization.
Request body (required): application/json, CreateLocalAccountRequest
| Response | Body | Meaning |
|---|---|---|
201 |
LocalAccountView |
The account |
403 |
— | Not an org admin |
422 |
— | Password too short |
PUT /api/local-accounts/{user_id}/password
Section titled “PUT /api/local-accounts/{user_id}/password”PUT /api/local-accounts/{user_id}/password — reset a password. There is no
email subsystem, so an admin reset is the recovery path (KAIROS-I-0018).
| Parameter | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
public.users.id |
Request body (required): application/json, SetPasswordRequest
| Response | Body | Meaning |
|---|---|---|
204 |
— | Set; every session that person held is revoked |
403 |
— | Not an org admin |
404 |
— | No such user in this organization |
422 |
— | Password too short |
GET /api/local-accounts/{user_id}/sessions
Section titled “GET /api/local-accounts/{user_id}/sessions”GET /api/local-accounts/{user_id}/sessions.
| Parameter | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
public.users.id |
| Response | Body | Meaning |
|---|---|---|
200 |
SessionListResponse |
Sessions, newest first |
403 |
— | Not an org admin |
404 |
— | No such user in this organization |
DELETE /api/local-accounts/{user_id}/sessions
Section titled “DELETE /api/local-accounts/{user_id}/sessions”DELETE /api/local-accounts/{user_id}/sessions — end every session, without
changing the password.
Separate from a reset on purpose: “log this person out of everywhere” and “they have forgotten their password” are different incidents, and forcing the first to change the password would mean telling the person a new one they did not ask for.
| Parameter | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
public.users.id |
| Response | Body | Meaning |
|---|---|---|
204 |
— | Every session is revoked |
403 |
— | Not an org admin |
404 |
— | No such user in this organization |