Auth API
Authentication and user management endpoints.
GET /api/health
Health check endpoint. Returns a simple status to confirm the API is running.
Auth: None
Response 200:
{
"status": "ok"
}
Used as the Kubernetes liveness probe: it checks only that the process is serving.
GET /api/health/ready
Readiness check used by the Kubernetes readiness probe. Returns 200 when PostgreSQL answers
and the pod is not shutting down; otherwise 503. Redis is reported in checks.redis but does
not affect readiness: during a Redis outage replicas stay in the Service and only the
Redis-backed flows (OAuth login state, exchange and OIDC codes) answer 503. Error details are
logged, not returned.
Auth: None
Response 200:
{ "status": "ready", "checks": { "db": "ok", "redis": "ok" } }
During a Redis outage: 200 with { "status": "ready", "checks": { "db": "ok", "redis": "unavailable" } }.
Response 503: { "status": "not_ready", "checks": { "db": "unavailable", "redis": "ok" } } or { "status": "draining" }.
POST /api/auth/login
Authenticates a user with email (or username) and password.
Auth: None (rate-limited per IP)
Request Body:
{
"email": "[email protected]",
"password": "..."
}
Response 200 — session:
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": { "id": "...", "email": "[email protected]", "name": "Admin", "role": "admin" }
}
The session JWT carries amr (["pwd"], plus "otp", "mfa" after a second factor) and
auth_time.
Response 200 — MFA enabled (no session yet):
{
"mfa_required": true,
"status": "mfa_required",
"challengeToken": "eyJ...",
"expiresIn": 300,
"methods": ["totp", "recovery_code"]
}
Complete the login with POST /api/auth/mfa/challenge { challengeToken, code }.
Response 200 — role requires MFA, not enrolled: { token, user, mfaEnrollmentRequired: true }.
The token only reaches /api/auth/mfa/status|enroll|verify and GET /api/users/me; every
other endpoint answers 403 { "error": "mfa_enrollment_required" } until enrolment is verified.
Error 401: { "error": "Invalid credentials." }
GitHub/GitLab logins (POST /api/auth/exchange) return the same three shapes, with amr: ["fed"].
MFA endpoints
See Multi-factor authentication for the full flow.
| Method | Path | Body | Result |
|---|---|---|---|
POST |
/api/auth/mfa/challenge |
{ challengeToken, code } |
{ token, user }; 401 invalid_code / invalid_challenge; 429 when rate-limited |
GET |
/api/auth/mfa/status |
— | { enabled, pending, recoveryCodesRemaining, required, requiredRoles, stepUpMaxAgeSec } |
POST |
/api/auth/mfa/enroll |
— | { otpauthUri, qrDataUrl, secret, issuer } (409 if already enabled) |
POST |
/api/auth/mfa/verify |
{ code } |
{ recoveryCodes, token, user } |
POST |
/api/auth/mfa/step-up |
{ code } |
{ token } with auth_time = now |
POST |
/api/auth/mfa/recovery-codes |
{ code } |
{ recoveryCodes } |
POST |
/api/auth/mfa/disable |
{ code } |
{ success }; 403 mfa_required_by_policy |
POST |
/api/users/:id/mfa/reset |
{ reason? } |
admin + step-up; { success, hadMfa } |
GET / PUT |
/api/settings/mfa |
{ requiredRoles } |
policy mfa.requiredRoles (PUT: admin + step-up) |
Step-up: secret reveal/export, POST /api/settings/rotate-secrets, POST /api/agent-tokens,
admin MFA reset and PUT /api/settings/mfa answer 401 { "error": "step_up_required", "maxAgeSec": 900 }
unless the session verified a second factor within MFA_STEP_UP_MAX_AGE_SEC. Agent tokens are not
subject to step-up.
GET /api/auth/gitlab
Initiates GitLab OAuth flow. Redirects to the callback endpoint with a mock authorization code.
Auth: None
Response 302: Redirect to /api/auth/gitlab/callback?code=mock_gitlab_code
GET /api/auth/gitlab/callback
GitLab OAuth callback. Creates or updates a user from the GitLab profile, generates a JWT, and redirects to the portal dashboard with the token.
Auth: None
Query Parameters:
| Param | Type | Description |
|---|---|---|
| code | string | Authorization code (mock) |
Response 302: Redirect to {PORTAL_URL}/dashboard?token={jwt}
GET /api/users/init-demo
Seeds the database with four demo users if they do not already exist:
| Name | Role | |
|---|---|---|
| Admin | [email protected] | admin |
| John Dev | [email protected] | developer |
| Sarah Lead | [email protected] | tech_lead |
| DevOps Boss | [email protected] | devops |
Auth: None
Response 200:
{
"message": "Created 4 new demo users",
"users": [
{ "id": "00000000-0000-0000-0000-000000000001", "name": "Admin", "email": "[email protected]", "role": "admin" }
]
}
GET /api/users/me
Returns the currently authenticated user's profile, including the linked custom role (roleRef) if assigned.
Auth: Bearer token (any authenticated user)
Response 200:
{
"id": "00000000-0000-0000-0000-000000000001",
"email": "[email protected]",
"name": "Admin",
"role": "admin",
"roleId": null,
"roleRef": null,
"gitlabId": null,
"avatarUrl": null,
"lastLogin": "2026-07-01T12:00:00.000Z",
"isActive": true,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-07-01T12:00:00.000Z"
}
PATCH /api/users/me
Updates the current user's profile. Only name and avatarUrl can be modified.
Auth: Bearer token (any authenticated user)
Request Body:
{
"name": "New Name",
"avatarUrl": "https://example.com/avatar.png"
}
Response 200:
{
"id": "...",
"name": "New Name",
"email": "[email protected]",
"role": "admin",
"avatarUrl": "https://example.com/avatar.png"
}
GET /api/users
Lists all users. Requires DEVOPS or TECH_LEAD role.
Auth: Bearer token (DEVOPS, TECH_LEAD)
Response 200:
[
{
"id": "00000000-0000-0000-0000-000000000001",
"email": "[email protected]",
"name": "Admin",
"role": "admin"
}
]
POST /api/users
Creates a new user. Requires DEVOPS role. Audit-logged.
Auth: Bearer token (DEVOPS)
Request Body:
{
"name": "New User",
"email": "[email protected]",
"role": "developer",
"gitlabId": null,
"avatarUrl": null
}
Response 201:
{
"id": "88888888-8888-8888-8888-888888888888",
"name": "New User",
"email": "[email protected]",
"role": "developer",
"gitlabId": null,
"avatarUrl": null
}
PUT /api/users/:id
Updates an existing user's details. Requires DEVOPS role. Audit-logged.
Auth: Bearer token (DEVOPS)
Request Body: (all fields optional)
{
"name": "Updated Name",
"email": "[email protected]",
"role": "tech_lead",
"gitlabId": "gitlab-123",
"avatarUrl": "https://example.com/avatar.png"
}
Response 200:
{
"id": "...",
"name": "Updated Name",
"email": "[email protected]",
"role": "tech_lead"
}
Error 404:
{ "error": "User not found" }
PATCH /api/users/:id/role
Changes a user's role assignment. Supports setting both the built-in role enum and a custom role ID. Requires users.assign-role permission. Clears permission cache for that user.
Auth: Bearer token (users.assign-role permission)
Request Body:
{
"role": "tech_lead",
"roleId": "uuid-of-custom-role"
}
Response 200:
{
"id": "...",
"role": "tech_lead",
"roleId": "uuid-of-custom-role"
}
DELETE /api/users/:id
Hard-deletes a user from the database. Requires DEVOPS role. Audit-logged.
Auth: Bearer token (DEVOPS)
Response 200:
{ "success": true }
POST /api/users/invite
Invites a new user by email. Requires users.create permission. Returns 409 if the email already exists. Audit-logged.
Auth: Bearer token (users.create permission)
Request Body:
{
"email": "[email protected]",
"name": "Invited User",
"role": "developer",
"roleId": null
}
Response 201:
{
"id": "...",
"name": "Invited User",
"email": "[email protected]",
"role": "developer"
}
Error 409:
{ "error": "User with this email already exists" }
GET /api/users/:id/permissions
Returns the computed set of permissions for a given user. Merges role preset permissions with custom role permissions. Uses an in-memory cache (TTL: 60s).
Auth: Bearer token (any authenticated user)
Response 200:
{
"userId": "uuid",
"role": "devops",
"roleId": null,
"permissions": [
"users.list",
"users.create",
"projects.list",
"deployments.trigger",
"..."
]
}
Roles CRUD
GET /api/roles
Lists all custom roles. Requires users.list permission.
Response 200:
[
{
"id": "uuid",
"name": "custom-role",
"description": "My custom role",
"permissions": ["projects.list", "deployments.read"],
"isSystem": false,
"isActive": true
}
]
GET /api/roles/:id
Gets a single role by ID. Requires users.list permission.
POST /api/roles
Creates a new custom role. Requires users.create permission. Returns 409 if name already exists. Audit-logged.
Request Body:
{
"name": "custom-role",
"description": "Optional description",
"permissions": ["projects.list", "deployments.read"]
}
PUT /api/roles/:id
Updates a custom role. System roles cannot be modified. Clears permission cache for all users with this role. Requires users.update permission. Audit-logged.
Request Body:
{
"name": "updated-role",
"description": "Updated description",
"permissions": ["projects.list", "projects.create"],
"isActive": true
}
DELETE /api/roles/:id
Deletes a custom role. System roles cannot be deleted. Unassigns the role from all users. Requires users.delete permission. Audit-logged.
Response 200:
{ "success": true }
Permission Validation
GET /api/permissions
Returns the full list of all available permissions in the system. Requires users.list permission.
Response 200:
{
"users.list": "List all users",
"users.create": "Create new users",
"projects.list": "List all projects",
"...": "..."
}
POST /api/roles/:id/permissions/validate
Validates an array of permission strings against the known permission set. Returns lists of valid and invalid entries. Requires users.update permission.
Request Body:
{
"permissions": ["projects.list", "invalid.perm", "deployments.read"]
}
Response 200:
{
"valid": ["projects.list", "deployments.read"],
"invalid": ["invalid.perm"],
"totalValid": 2,
"totalInvalid": 1
}
Error Codes
| Status | Code | Description |
|---|---|---|
| 401 | Unauthorized: Missing token |
No Bearer token provided |
| 401 | Invalid credentials. |
Wrong email/username or password |
| 401 | step_up_required |
Action needs a recent second factor |
| 401 | invalid_code |
Wrong, reused or replayed MFA code |
| 403 | mfa_enrollment_required |
Session restricted to MFA enrolment |
| 404 | User not found |
User ID does not exist |
| 409 | User with this email... |
Duplicate email on invite |
| 409 | Role with this name... |
Duplicate role name |
| 400 | Cannot modify system roles |
Attempted to edit a system role |
| 400 | Cannot delete system roles |
Attempted to delete a system role |
| 400 | Email and name are required |
Missing required fields on invite |