HTTP API
API Reference
This reference describes the current Identity routes and the separately hosted, server-to-server Governance endpoint. Protected endpoints accept the secure session cookie or an Authorization: Bearer access token. Use the Developer Toolkit for copyable patterns and local sample tools.
The public GET /api route is a small liveness response, not this documentation. Readiness at GET /api/ready checks persistence. Neither health route authenticates a user.
Identity: health and authentication
| Method and path | Access | Behavior |
|---|---|---|
GET /api/health | Public | Process liveness response; does not verify PostgreSQL. |
GET /api/ready | Public | Checks repository readiness; returns 503 if persistence is unavailable. |
POST /api/auth/register | Public | JSON: email, password (12–128 characters), optional name. Creates an account and session; returns 201. |
POST /api/auth/login | Public | JSON: email and password. Returns a short-lived access token and sets HttpOnly session cookies. |
POST /api/auth/refresh | Refresh cookie or token | Rotates the refresh session and issues a new access token. |
GET /api/auth/me | Signed-in user | Returns the authenticated user after verifying the active session. |
POST /api/auth/logout | Signed-in user | Revokes the current session and clears session cookies. |
Account: own profile, sessions, and activity
| Method and path | Behavior |
|---|---|
GET /api/account/profile | Read the signed-in user's profile. |
PATCH /api/account/profile | JSON: {"name":"New display name"}. Updates the display name only. |
GET /api/account/sessions | List up to 50 of the user's recent sessions and active count. |
POST /api/account/sessions/{sessionId}/revoke | Revoke a session belonging to the signed-in user. |
GET /api/account/activity?limit=20 | Read recent account audit activity; limit is 1–50. |
GET /api/account/security | Read session counts, last login, membership date, and MFA flag. MFA enrollment is not available in this release. |
Administrator: restricted operations
All /api/admin/* endpoints require an authenticated account with the administrator role. Do not expose administrator credentials or use these endpoints from public client-side code.
| Method and path | Behavior |
|---|---|
GET /api/admin/overview | Read operational account/session/audit/quarantine totals. |
GET /api/admin/users?limit=25&offset=0&search= | Search and page through users. |
PATCH /api/admin/users/{userId}/role | Change a user role through audited maker-checker protections. |
GET /api/admin/sessions?limit=25&offset=0&active=true | Page through sessions; active filter is optional. |
POST /api/admin/sessions/{sessionId}/revoke | Revoke a session by administrator action. |
GET /api/admin/audit-logs?limit=50&offset=0 | Page through audit events, optionally filtered by event type. |
GET /api/admin/quarantine?limit=25&offset=0 | Page through quarantine records; optional status filter is QUARANTINED or COMMITTED. |
Governance: server-to-server evaluation
The Governance service listens separately (default local port 4000). It is not a public browser API. The calling API must authenticate to Identity first, then call Policy with a server-only bearer token, a verified subject role, a server-selected target domain, action, and SHA-256 payload hash.
| Method and path | Access | Request fields | Result |
|---|---|---|---|
POST /api/v1/governance/evaluate | Configured service principal bearer token | requestId, targetDomainId, action (READ/WRITE/EXECUTE), payloadHash (64 lowercase hex), optional verified subjectId and mapped subjectRole. | Signed verdict with allowed, reason, enforced rule, proof hash, timestamp, and signature. Unknown/malformed requests fail; callers must fail closed. |
Example: sign in without putting credentials in source control
curl -i "$IDENTITY_URL/api/auth/login" \
-H 'Content-Type: application/json' \
--data '{"email":"you@example.test","password":"REPLACE_WITH_YOUR_PASSWORD"}'Use HTTPS and the HttpOnly session cookie in browser flows. Treat any access token returned in the JSON body as a secret; never commit it, place it in a URL, or store it in browser local storage. Authentication writes are origin-checked and rate-limited.
Typical responses: 400 invalid input, 401 invalid or expired credentials, 403 rejected cross-site write or policy denial, 409 duplicate registration, 429 rate limit, and 503 unavailable persistence/upstream service. See troubleshooting, Quickstart, and trust boundaries.