Skip to content

API — Auth, identity & RBAC

Purpose

Authentication (login, password change), the signed-in user's own profile/history (/api/me), and the administrative management of users, roles, and the permission catalog.

Auth & roles

  • Login endpoints are [AllowAnonymous]; everything else needs a Bearer JWT.
  • /api/me/* is [Authorize] only — no permission policy; the server scopes to the caller.
  • Users / Roles / Permissions are administrative — gated on admin.users / admin.roles (held by SYS_ADMIN; these are admin-scope permissions — see the RBAC matrix).

Endpoints

Auth — base /api/auth

Method Path Purpose Gate
POST /api/auth/login Username/password → 8h JWT AllowAnonymous
POST /api/auth/change-password Change own password [Authorize]
POST /api/auth/login-dev Dev convenience login AllowAnonymous
POST /api/auth/dev-token Dev token mint AllowAnonymous

Me — base /api/me

Method Path Purpose
GET /api/me/profile Own profile
PATCH /api/me/profile Update own profile
GET /api/me/login-history Own login history

Users — base /api/users · gate admin.users

Method Path Purpose
GET / POST /api/users List / create users
GET / PATCH / DELETE /api/users/{id} Read / update / remove a user
POST /api/users/{id}/lock · /unlock Lock / unlock an account
POST /api/users/{id}/reset-password Admin password reset
GET /api/users/{id}/login-history A user's login history
POST /api/users/{userId}/roles Grant a role
DELETE /api/users/{userId}/roles/{userRoleId} Revoke a role grant

Roles & permissions

Method Path Purpose Gate
GET / POST /api/roles List / create roles admin.roles
GET / PATCH / DELETE /api/roles/{id} Read / update / delete a role admin.roles
GET /api/permissions The global permission catalog admin.roles

Shapes & errors

Login returns the JWT + expiry (ExpiresAt). Role grants carry optional department scope + effective dates (see Auth & RBAC architecture). Standard ProblemDetails on failure; account lockout returns a 4xx with the lockout reason.

Gotchas

  • login-dev / dev-token are dev helpers — convenience auth, not a production path.
  • Account protection is real — failed_login_count + lockout_until drive lockout.
  • No refresh token — on 8h expiry the client re-logs-in.
  • The permission catalog is global (no BU scope); roles are tenant-scoped.