getList users
users.readAuthentication: 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 /usersResponses
Response
{
"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.