getList users

Required capabilityusers.read

Authentication: Send Authorization: Bearer <access_token>.

Lists users directly under scope_ref. With include_descendants=true, scope_ref must identify an enterprise and the response includes users of that enterprise and its clients in one page sequence. Subtree mode requires users.read over the subtree and does not apply the status or identity_source filters; those filters apply only to the direct-scope listing.

Parameters

Name Location Type Required Description and constraints
scope_ref query string Yes pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
status query "active" / "suspended" / "deactivated" / "pending_activation" / "invited" or "active" / "suspended" / "deactivated" / "pending_activation" / "invited"[] No
identity_source query "platform-managed" / "federated" or "platform-managed" / "federated"[] No
include_descendants query "true" / "false" No
page_size query integer No Cursor pagination page size. The canonical contract accepts integers from 1 to 500. minimum: 1; maximum: 500; default: 100
page_token query string No Opaque cursor returned by a previous page.

Request

Request URL

GET
GET /users

Responses

Response

application/json
{
  "items": [
    {
      "created_at": "2026-05-01T10:00:00Z",
      "display_name": "Jane Doe",
      "email": "jane.doe@acme.example",
      "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
      "federation": null,
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "identity_source": "platform-managed",
      "resource": "human_actor",
      "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "status": "active",
      "updated_at": "2026-05-01T10:00:00.000Z"
    }
  ],
  "next_page_token": null
}

Operation succeeded.

Response 200 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
items object[] Yes
next_page_token string or null Yes

Additional fields are not accepted.

application/json body.items

Type: object[].

application/json body.items item
Field Type Required Description and constraints
access_resend_event_id string or null No
created_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
display_name string or null No
email string or null No
email_changed_at string or null No
etag string Yes minLength: 1
federation object or null No
federation_conflict string or null No
id string Yes format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
identity_source "platform-managed" / "federated" / "system" Yes
last_suspended_at string or null No
previous_email string or null No
recovered_at string or null No
recovery_id string or null No
recovery_request object or null No
recovery_requested_at string or null No
resource "human_actor" Yes
scope_ref string Yes pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
status "active" / "suspended" / "deactivated" / "pending_activation" / "invited" Yes
updated_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Additional fields are not accepted.

application/json body.items item.access_resend_event_id

At least one alternative must match.

application/json body.items item.access_resend_event_id: alternative 1

Type: string. format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

application/json body.items item.access_resend_event_id: alternative 2

Type: null.

application/json body.items item.display_name

At least one alternative must match.

application/json body.items item.display_name: alternative 1

Type: string.

application/json body.items item.display_name: alternative 2

Type: null.

application/json body.items item.email

At least one alternative must match.

application/json body.items item.email: alternative 1

Type: string. format: email; pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

application/json body.items item.email: alternative 2

Type: null.

application/json body.items item.email_changed_at

At least one alternative must match.

application/json body.items item.email_changed_at: alternative 1

Type: string. format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

application/json body.items item.email_changed_at: alternative 2

Type: null.

application/json body.items item.federation

At least one alternative must match.

application/json body.items item.federation: alternative 1
Field Type Required Description and constraints
external_subject string Yes minLength: 1
issuer string Yes minLength: 1

Additional fields are not accepted.

application/json body.items item.federation: alternative 2

Type: null.

application/json body.items item.federation_conflict

At least one alternative must match.

application/json body.items item.federation_conflict: alternative 1

Type: string.

application/json body.items item.federation_conflict: alternative 2

Type: null.

application/json body.items item.last_suspended_at

At least one alternative must match.

application/json body.items item.last_suspended_at: alternative 1

Type: string. format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

application/json body.items item.last_suspended_at: alternative 2

Type: null.

application/json body.items item.previous_email

At least one alternative must match.

application/json body.items item.previous_email: alternative 1

Type: string. format: email; pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

application/json body.items item.previous_email: alternative 2

Type: null.

application/json body.items item.recovered_at

At least one alternative must match.

application/json body.items item.recovered_at: alternative 1

Type: string. format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

application/json body.items item.recovered_at: alternative 2

Type: null.

application/json body.items item.recovery_id

At least one alternative must match.

application/json body.items item.recovery_id: alternative 1

Type: string. format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

application/json body.items item.recovery_id: alternative 2

Type: null.

application/json body.items item.recovery_request

At least one alternative must match.

application/json body.items item.recovery_request: alternative 1
Field Type Required Description and constraints
approval_id string or null Yes
created_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
new_email string or null Yes
reason string or null Yes
request_id string Yes format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
state "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" Yes

Additional fields are not accepted.

application/json body.items item.recovery_request: alternative 1.approval_id

At least one alternative must match.

application/json body.items item.recovery_request: alternative 1.approval_id: alternative 1

Type: string. format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

application/json body.items item.recovery_request: alternative 1.approval_id: alternative 2

Type: null.

application/json body.items item.recovery_request: alternative 1.new_email

At least one alternative must match.

application/json body.items item.recovery_request: alternative 1.new_email: alternative 1

Type: string. format: email; pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

application/json body.items item.recovery_request: alternative 1.new_email: alternative 2

Type: null.

application/json body.items item.recovery_request: alternative 1.reason

At least one alternative must match.

application/json body.items item.recovery_request: alternative 1.reason: alternative 1

Type: string.

application/json body.items item.recovery_request: alternative 1.reason: alternative 2

Type: null.

application/json body.items item.recovery_request: alternative 2

Type: null.

application/json body.items item.recovery_requested_at

At least one alternative must match.

application/json body.items item.recovery_requested_at: alternative 1

Type: string. format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

application/json body.items item.recovery_requested_at: alternative 2

Type: null.

application/json body.next_page_token

At least one alternative must match.

application/json body.next_page_token: alternative 1

Type: string.

application/json body.next_page_token: alternative 2

Type: null.

Response 400 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
code string Yes
data object No No additional fields
details object No Additional fields allowed
message string Yes

Additional fields are not accepted.

application/json body.data
Field Type Required Description and constraints
acr_values string No RFC 9470 step-up challenge (insufficient_user_authentication).
blockers object[] No For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
code string No For legal refusals: the document code the refusal is about.
max_age string No RFC 9470 step-up challenge (insufficient_user_authentication).
max_source_amount object No For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields
min_source_amount object No For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields
published_version string No For document_version_superseded: the version currently published.
reason string No Typed refinement of code, from the failing service's contract.
resource string No Resource kind a resource_not_found refers to.
retry_after_ms integer No Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0
source string No For not_admissible: the gate that denied (verification, lifecycle, policy, compliance).

Additional fields are not accepted.

application/json body.data.blockers

For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.

Type: object[].

application/json body.data.blockers item
Field Type Required Description and constraints
description string Yes
type "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" Yes
assets object[] No minItems: 1
count integer No minimum: 0; maximum: 9007199254740991

Additional fields are not accepted.

application/json body.data.blockers item.assets

Type: object[]. minItems: 1

application/json body.data.blockers item.assets item
Field Type Required Description and constraints
asset string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
kind "balance" / "held" / "owed" / "unsettled" Yes

Additional fields are not accepted.

application/json body.data.max_source_amount

For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

application/json body.data.min_source_amount

For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

Response 401 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
code string Yes
data object No No additional fields
details object No Additional fields allowed
message string Yes

Additional fields are not accepted.

application/json body.data
Field Type Required Description and constraints
acr_values string No RFC 9470 step-up challenge (insufficient_user_authentication).
blockers object[] No For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
code string No For legal refusals: the document code the refusal is about.
max_age string No RFC 9470 step-up challenge (insufficient_user_authentication).
max_source_amount object or null No For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields
min_source_amount object No For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields
published_version string No For document_version_superseded: the version currently published.
reason string No Typed refinement of code, from the failing service's contract.
resource string No Resource kind a resource_not_found refers to.
retry_after_ms integer or null No Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0
source string No For not_admissible: the gate that denied (verification, lifecycle, policy, compliance).

Additional fields are not accepted.

application/json body.data.blockers

For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.

Type: object[].

application/json body.data.blockers item
Field Type Required Description and constraints
description string Yes
type "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" Yes
assets object[] No minItems: 1
count integer No minimum: 0; maximum: 9007199254740991

Additional fields are not accepted.

application/json body.data.blockers item.assets

Type: object[]. minItems: 1

application/json body.data.blockers item.assets item
Field Type Required Description and constraints
asset string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
kind "balance" / "held" / "owed" / "unsettled" Yes

Additional fields are not accepted.

application/json body.data.max_source_amount

For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

application/json body.data.min_source_amount

For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

Response 403 schema

Content type: application/json.

See response 401 schema.

Response 500 schema

Content type: application/json.

See response 401 schema.

Response 502 schema

Content type: application/json.

See response 400 schema.

Response 503 schema

Content type: application/json.

See response 400 schema.