REST API

Everything lives under iam.api.base-path (default /api/iam/v1). Full OpenAPI docs are served by your running app (Swagger group iam) — this page is the map.

Authentication

Endpoint	Purpose
POST /auth/login	Email + password → access & refresh tokens (2FA challenge if enabled)
POST /auth/refresh	Rotate the refresh token, mint a new access token
POST /auth/logout	Revoke the refresh token
POST /auth/forgot-password / reset-password	Password reset flow
GET /auth/oauth2/{provider}/authorize	Begin OAuth2/OIDC login (PKCE)
GET /auth/oauth2/{provider}/callback	Provider redirect target
POST /auth/oauth2/token-exchange	SPA exchanges the one-time code for tokens
POST /auth/2fa/verify	Complete a 2FA challenge
GET /.well-known/jwks.json	Public JWK Set for verifying ES256-signed tokens (permitAll; present only when the JWT algorithm is asymmetric — not in HS512 mode)

Rate limits apply per endpoint (configurable; sensible defaults on).

Runtime (what your app calls)

Endpoint	Purpose
GET /me/permissions	The resolved permission object — roles, features, actions, field access
GET /me/permissions?scopeId=…	Scoped resolution (Scoped RBAC)
GET /me/profile	Current user profile
POST /me/check-access	Ad-hoc access question (resource/action/field), optional explain trace
POST /access-simulations	Admin explain API — “why can (or can’t) user X do Y?” with the full decision trace. Requires iam_permissions:simulate

Management (admin surface)

Area	Endpoints
Users	GET/POST /users, GET/PUT/DELETE /users/{id}, role & group assignment
Roles	GET/POST /roles, hierarchy via parentRoleId, permission attachment
Groups	GET/POST /groups, membership, group-role grants
Resources	GET/POST /resources, fields, action linking
Actions	GET/POST /actions (system actions immutable)
Permissions	GET/POST/DELETE /permissions — resource × action (× field) × effect
Scopes	GET/POST /scopes, scoped role assignment
Tenants	management endpoints (multi-tenant mode)
Audit	GET /audit, filtered search + export
OAuth2 providers	per-tenant provider configuration (secrets encrypted at rest)

Every management endpoint is itself guarded by IAM’s own iam_* resources — the admin surface eats its own dog food.

Errors

Every error is an RFC 7807 Problem Details body (application/problem+json), rendered through one exception advice so the shape is uniform:

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: loans:approve",
  "correlationId": "b1f3c8a2-…"
}

correlationId is the RFC 7807 extension member IAM stamps on every error body (the inbound X-Correlation-Id or a generated UUID) — quote it in a bug report to join the response to server logs and audit rows. Validation failures (400) additionally carry an errors object of field → message.

401 = unauthenticated, 403 = authenticated but not permitted (implicit deny included), 404 on tenant-foreign entities in multi-tenant mode (existence is not leaked).