Skip to content

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 ​

StatusCodeDetail
400limit must be a positive integerInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
500authentication service unavailableInternal 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) ​

FieldTypeRequired
display_namestringNo
emailstringNo
initial_passwordstringNo
passwordstringNo
usernamestringYes
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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
409the resource already existsConflict
422weak_passwordWeak Password
500authentication service unavailableInternal 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) ​

FieldTypeRequired
idsarray<string>No
opstringYes
json
{
  "ids": [
    "01J8Z3USER000000000000001",
    "01J8Z3USER000000000000002"
  ],
  "op": "disable"
}

Responses ​

  • 200 — Successful response
json
{
  "results": [
    {
      "id": "01J8Z3USER000000000000001",
      "ok": true
    },
    {
      "error": "not_found",
      "id": "01J8Z3USER000000000000002",
      "ok": false
    }
  ]
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
422a maximum of 500 ids is allowedInvalid Operation; Too Many Items
422op must be disable or enableInvalid Operation; Too Many Items
500authentication service unavailableInternal 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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
415Content-Type must be text/csvUnsupported Media Type
422CSV header must be username,email,display_name,passwordInvalid CSV
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

GET /users/{id} ​

Get a user

Use to retrieve one administrative user record by ULID.

Required permission — iam:users:any

Path parameters ​

ParameterDescription
idPath 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 ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
display_namestringNo
emailstringNo
statusstringNo
usernamestringNo
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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath 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 ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
422email_not_verifiedInvalid Request
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath 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 ​

StatusCodeDetail
400limit must be a positive integerInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
kindstringYes
passwordstringNo
json
{
  "kind": "password",
  "password": "AtLeastTwelve1"
}

Responses ​

  • 200 — Successful response
json
{
  "kind": "password",
  "user_id": "01J8Z3USER000000000000001",
  "username": "alice"
}

Errors ​

StatusCodeDetail
400kind must be password or serviceInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
422weak_passwordWeak Password
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath 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 ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "created_at": "2026-01-01T00:00:00Z",
  "expires_at": "2026-01-08T00:00:00Z",
  "user_status": "invited"
}

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath 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 ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal 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 ​

ParameterDescription
idPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error