Appearance
Users API Reference
GET /users/
List users
Use from an administrator console to list all users, ordered by ascending user ID. Cursors are user ULIDs. See REST pagination for the shared collection contract.
Required permission — iam:users:any
Responses
- 200 — Successful response
json
{
"items": [
{
"created_at": "2026-01-01T00:00:00Z",
"display_name": "Alice Example",
"email": "alice@example.test",
"email_verified_at": "2026-01-01T00:00:00Z",
"failed_logins": 0,
"id": "01J8Z3USER000000000000001",
"perm_ver": 3,
"status": "active",
"updated_at": "2026-01-01T00:00:00Z",
"username": "alice"
}
],
"next_cursor": ""
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | limit must be a positive integer | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 500 | authentication service unavailable | Internal Server Error |
POST /users/
Create a user
Use from an administrator or provisioning workflow to create an active user. Password and initial_password are optional; password wins when both are supplied.
Required permission — iam:users:any
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| display_name | string | No |
| string | No | |
| initial_password | string | No |
| password | string | No |
| username | string | Yes |
json
{
"display_name": "Alice Example",
"email": "alice@example.test",
"password": "AtLeastTwelve1",
"username": "alice"
}Responses
- 200 — Successful response
json
{
"created_at": "2026-01-01T00:00:00Z",
"display_name": "Alice Example",
"email": "alice@example.test",
"email_verified_at": "2026-01-01T00:00:00Z",
"failed_logins": 0,
"id": "01J8Z3USER000000000000001",
"perm_ver": 3,
"status": "active",
"updated_at": "2026-01-01T00:00:00Z",
"username": "alice"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 409 | the resource already exists | Conflict |
| 422 | weak_password | Weak Password |
| 500 | authentication service unavailable | Internal Server Error |
POST /users/batch
Enable or disable users in batches
Use for administrative bulk status changes. Up to 500 IDs are processed independently; each result records success or invalid_id, not_found, or operation_failed.
Required permission — iam:users:any When op is disable, requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. enable does not require fresh authentication.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| ids | array<string> | No |
| op | string | Yes |
json
{
"ids": [
"01J8Z3USER000000000000001",
"01J8Z3USER000000000000002"
],
"op": "disable"
}Responses
- 200 — Successful response
json
{
"results": [
{
"id": "01J8Z3USER000000000000001",
"ok": true
},
{
"error": "not_found",
"id": "01J8Z3USER000000000000002",
"ok": false
}
]
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 422 | a maximum of 500 ids is allowed | Invalid Operation; Too Many Items |
| 422 | op must be disable or enable | Invalid Operation; Too Many Items |
| 500 | authentication service unavailable | Internal Server Error |
POST /users/import
Import users from CSV
Use for bulk provisioning from an administrator export. Send text/csv with exactly username,email,display_name,password columns and at most 500 data rows; each row is reported independently.
Required permission — iam:users:any
Responses
- 200 — Successful response
json
{
"results": [
{
"id": "01J8Z3USER000000000000001",
"ok": true,
"row": 2,
"username": "alice"
},
{
"error": "weak_password",
"ok": false,
"row": 3,
"username": "bob"
}
]
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 415 | Content-Type must be text/csv | Unsupported Media Type |
| 422 | CSV header must be username,email,display_name,password | Invalid CSV |
| 500 | authentication service unavailable | Internal Server Error |
DELETE /users/{id}
Delete a user
Use for an administrative hard deletion. Cascaded records are removed and the operation is audited; prefer account erasure for self-service privacy requests.
Required permission — iam:users:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
GET /users/{id}
Get a user
Use to retrieve one administrative user record by ULID.
Required permission — iam:users:any
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"created_at": "2026-01-01T00:00:00Z",
"display_name": "Alice Example",
"email": "alice@example.test",
"email_verified_at": "2026-01-01T00:00:00Z",
"failed_logins": 0,
"id": "01J8Z3USER000000000000001",
"perm_ver": 3,
"status": "active",
"updated_at": "2026-01-01T00:00:00Z",
"username": "alice"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
PATCH /users/{id}
Update a user
Use for administrative profile or status changes. At least one of username, email, display_name, and status is required; status may be active or disabled.
Required permission — iam:users:any Setting a non-null email or disabling a user requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Other profile changes do not require fresh authentication.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| display_name | string | No |
| string | No | |
| status | string | No |
| username | string | No |
json
{
"display_name": "Alice Smith",
"status": "active"
}Responses
- 200 — Successful response
json
{
"created_at": "2026-01-01T00:00:00Z",
"display_name": "Alice Smith",
"email": "alice@example.test",
"failed_logins": 0,
"id": "01J8Z3USER000000000000001",
"perm_ver": 3,
"status": "active",
"updated_at": "2026-01-01T00:00:00Z",
"username": "alice"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
POST /users/{id}/approve
Approve a pending user
Use in approval registration mode after the user has verified email. The administrator's user bearer is recorded as approver; unverified accounts return email_not_verified.
Required permission — iam:users:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"approved_at": "2026-01-02T00:00:00Z",
"approved_by": "01J8Z3ADMIN000000000000001",
"created_at": "2026-01-01T00:00:00Z",
"display_name": "Alice Example",
"email": "alice@example.test",
"email_verified_at": "2026-01-01T00:00:00Z",
"failed_logins": 0,
"id": "01J8Z3USER000000000000001",
"perm_ver": 1,
"status": "active",
"updated_at": "2026-01-02T00:00:00Z",
"username": "alice"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 422 | email_not_verified | Invalid Request |
| 500 | authentication service unavailable | Internal Server Error |
GET /users/{id}/credentials
List user credential metadata
Lists every credential kind for the path user in ascending kind order. kind is unique per user and is the cursor key. The response includes only kind, created_at, optional rotated_at, and must_change; hashes, secrets, tokens, and credential material are never returned. See REST collection pagination for the shared collection contract.
Required permission — iam:users:any Requires iam:users:any; reads do not require step-up authentication.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"items": [
{
"created_at": "2026-01-01T00:00:00Z",
"kind": "service",
"must_change": false,
"rotated_at": "2026-02-01T00:00:00Z"
}
],
"next_cursor": ""
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | limit must be a positive integer | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
POST /users/{id}/credentials
Create or rotate a user credential
Use to provision a password credential or a service credential. Service secrets are generated and returned exactly once; password hashes are never returned.
Required permission — iam:users:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| kind | string | Yes |
| password | string | No |
json
{
"kind": "password",
"password": "AtLeastTwelve1"
}Responses
- 200 — Successful response
json
{
"kind": "password",
"user_id": "01J8Z3USER000000000000001",
"username": "alice"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | kind must be password or service | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 422 | weak_password | Weak Password |
| 500 | authentication service unavailable | Internal Server Error |
POST /users/{id}/disable
Disable a user
Use as a dedicated administrative lock switch. It resets lockout state, revokes sessions, invalidates permissions, and emits the same lifecycle events as a disabled status update.
Required permission — iam:users:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"created_at": "2026-01-01T00:00:00Z",
"display_name": "Alice Example",
"email": "alice@example.test",
"failed_logins": 0,
"id": "01J8Z3USER000000000000001",
"perm_ver": 4,
"status": "disabled",
"updated_at": "2026-01-01T00:00:00Z",
"username": "alice"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
GET /users/{id}/invitation
Get a user's invitation metadata
Returns the latest persisted invitation row's timestamps and the user's actual stored status in user_status. A user without a persisted invitation row receives the generic not-found response. This does not report notification delivery or infer an accepted state.
Required permission — iam:users:any Requires iam:users:any; reads do not require step-up authentication.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"created_at": "2026-01-01T00:00:00Z",
"expires_at": "2026-01-08T00:00:00Z",
"user_status": "invited"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
GET /users/{id}/password-policy
Get a user's effective password policy
Use to inspect the resolved password requirements for one administrative user. The response contains only the merged policy.
Required permission — iam:users:any
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"breach_check": true,
"history_count": 5,
"min_length": 12,
"require_digit": true,
"require_letter": true,
"require_lower": false,
"require_symbol": false,
"require_upper": false
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |
DELETE /users/{id}/totp
Reset a user's TOTP
Use for administrative recovery when a user loses MFA access. It deletes active, pending, and backup-code credentials without requiring the user's TOTP code.
Required permission — iam:users:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.
Path parameters
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |