API Reference — Auth & RBAC

Auth & RBAC API

JSON endpoints for registration, login, token lifecycle, user roles, and permissions. See implementation in src/routes/auth.ts.

Conceptual guide: Auth & RBAC system • Deep dive: docs/auth-rbac.md

Public

POST /api/auth/register

{
  "email": "user@example.com",
  "password": "secret123",
  "name": "Jane"
}

201 → { user, tokens }; 409 if email exists.

POST /api/auth/login

{
  "email": "user@example.com",
  "password": "secret123"
}

200 → { user: { id, email, name, roles, permissions }, tokens }.

GET /api/auth/client-login

Accepts HTTP Basic Auth, sets localStorage.access_token, then redirects. Optional ?redirect=/app.

POST /api/auth/refresh

{
  "refresh_token": "..."
}

200 → { tokens }; rotates refresh token and revokes the old jti.

POST /api/auth/logout

{
  "refresh_token": "..."
}

200 → { success: true } (idempotent).

GET /api/auth/me

Requires Bearer access token. Returns current user payload.

Admin / Owner

POST /api/auth/roles/assign

{ "userId": "...", "role": "admin" }

GET /api/auth/roles

Lists available roles.

GET /api/auth/permissions

Lists available permissions.

POST /api/auth/permissions

{ "name": "view:analytics", "description": "..." }

DELETE /api/auth/permissions/:name

POST /api/auth/permissions/assign

{ "role": "admin", "permission": "view:analytics" }

POST /api/auth/permissions/unassign

{ "role": "admin", "permission": "view:analytics" }

GET /api/auth/role-permissions?role=admin

Returns permissions assigned to a role.

GET /api/auth/users

Query params: limit (max 100), offset, q (email/name contains).

PATCH /api/auth/users/:id

{ "email?": "...", "name?": "...", "status?": "active|disabled" }

DELETE /api/auth/users/:id

Notes

  • Auth required: Bearer access token; some endpoints require role admin or owner.
  • SQLite and MongoDB supported. IDs may be numeric (SQLite) or ObjectId (MongoDB); service handles coercion.
  • Token TTLs configured via AUTH_ACCESS_TTL and AUTH_REFRESH_TTL.