API Reference¶

Overview¶

The JustIAM REST API is documented using OpenAPI 3.0 (Swagger). You can explore it interactively at:

https://justiam.example.com/swagger/index.html

You can also download the spec directly:

YAML: https://justiam.example.com/swagger/doc.yaml
JSON: available via the Swagger UI

Authentication¶

Most endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <token>

A token can be:

Portal JWT — obtained via POST /api/v1/auth/login or an OIDC flow
Personal Access Token (PAT) — long-lived token created in the Profile page or via the API

See Personal Access Tokens for how to create a PAT.

Base URL¶

All management endpoints are under /api/v1/:

Single-tenant:

https://justiam.example.com/api/v1/

Multi-tenant (resolved from hostname):

https://<slug>.totmicro.com/api/v1/

All endpoints and auth semantics are identical in both modes. The tenant is determined by the Host header — no extra routing or path prefix is required.

OIDC/OAuth2 endpoints are at the root:

https://justiam.example.com/oauth2/ https://justiam.example.com/.well-known/

SAML endpoints:

https://justiam.example.com/saml/{app_id}/

---

## Pagination

List endpoints return paginated results. Query parameters:

| Parameter | Default | Description |
|---|---|---|
| `page` | `1` | Page number (1-based) |
| `limit` | `20` | Items per page |
| `search` | — | Filter by name/email (where supported) |

Response envelope:

```json
{
  "data": [...],
  "total": 150,
  "page": 1,
  "limit": 20
}

Error responses¶

All non-OAuth/OIDC error responses use the same JSON shape:

{
  "code": "optional_machine_readable_code",
  "message": "Description of what went wrong",
  "details": { "optional": "context-specific data" }
}

code and details are optional; message is always present. Clients should key error display off message and use code only when programmatically reacting to a specific condition (e.g. mfa_reauth_required).

OAuth 2.0 / OIDC endpoints (/oauth2/*) instead use the RFC 6749 §5.2 shape:

{
  "error": "invalid_request",
  "error_description": "missing client_id"
}

Status	Meaning
`400`	Bad request — validation error or missing field
`401`	Unauthenticated — missing or invalid token
`403`	Forbidden — insufficient permissions
`404`	Not found
`409`	Conflict — duplicate name, email, etc.
`500`	Internal server error

Health check¶

GET /healthz

Returns {"status":"ok"} with HTTP 200. No authentication required. Use this for load balancer and readiness probes.

Version¶

GET /api/v1/version

Returns the running version string. No authentication required.

Endpoint groups¶

Group	Base path	Permission
Authentication	`/api/v1/auth/`	Public / authenticated
Current user	`/api/v1/me/`	Authenticated
Users	`/api/v1/users/`	`users.*`
Groups	`/api/v1/groups/`	`groups.*`
Applications	`/api/v1/applications/`	`apps.*`
App Mappings	`/api/v1/app-mappings/`	`roles.*`
Admin Roles	`/api/v1/admin-roles/`	`admin_roles.manage`
Sessions	`/api/v1/sessions/`	`sessions.*`
Settings	`/api/v1/settings/`	Admin
Federated Providers	`/api/v1/federated/providers/`	`federated.manage`
Audit Log	`/api/v1/audit-logs/`	`audit.view`
MFA	`/api/v1/mfa/`	Authenticated
Personal Access Tokens	`/api/v1/me/tokens/`	Authenticated
Scheduled Tasks	`/api/v1/task-defs/`	Admin
Dashboard	`/api/v1/dashboard/`	Admin

For the full endpoint listing with request/response schemas, see the Swagger UI at /swagger/index.html.