IAM API Reference
The IAM service exposes a comprehensive REST API for authentication, user management, role-based access control, multi-factor authentication, API key lifecycle, session management, device fingerprinting, OAuth2 client administration, and user impersonation. All endpoints are served on port 8081 under the /api/v1 prefix.
Base URL
https://:hostname/api/v1All requests require the Content-Type: application/json header. Authenticated endpoints require a Bearer token in the Authorization header. Tenant-scoped endpoints require the X-Tenant-ID header.
Endpoint Groups
| Group | Base Path | Endpoints | Auth Required |
|---|---|---|---|
| Auth Endpoints | /api/v1/auth | 7 | No |
| User Endpoints | /api/v1/users | 12 | Yes |
| Role Endpoints | /api/v1/roles | 8 | Yes (Admin) |
| MFA Endpoints | /api/v1/mfa | 12 | Yes |
| API Key Endpoints | /api/v1/api-keys | 15 | Yes |
| Session Endpoints | /api/v1/sessions | 5 | Yes |
| Device Endpoints | /api/v1/devices | 9 | Yes |
| OAuth2 Endpoints | /api/v1/oauth2 | 5 | Yes (Admin) |
| Impersonation Endpoints | /api/v1/impersonation | 11 | Yes (Admin) |
Common Headers
| Header | Required | Description |
|---|---|---|
Authorization | Authenticated endpoints | Bearer followed by the JWT access token |
X-Tenant-ID | Tenant-scoped endpoints | UUID of the target tenant |
Content-Type | All POST/PUT/PATCH | Always application/json |
Common Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | BAD_REQUEST | Invalid request body or parameters |
| 401 | UNAUTHORIZED | Missing or expired authentication token |
| 403 | FORBIDDEN | Insufficient permissions for the operation |
| 404 | NOT_FOUND | Requested resource does not exist |
| 409 | CONFLICT | Resource already exists or state conflict |
| 423 | LOCKED | Account is locked due to failed login attempts |
| 429 | TOO_MANY_REQUESTS | Rate limit exceeded |
Pagination
Paginated endpoints accept standard Spring Data parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | int | 0 | Zero-based page index |
size | int | 20 | Number of items per page |
sort | string | varies | Sort field and direction (e.g., createdAt,desc) |
Paginated responses include a Page wrapper with content, totalElements, totalPages, number, and size fields.