list_end_users #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/list_end_users, with a bearer credential and the action's payload as the JSON body. It also accepts GET. An MCP connection lists this action as the tool tzcloud_list_end_users.
OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts (Sign-in, sessions, and tokens).
Build metadata: Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.
Contract description #
List an application's end users, paged: each user's id, creation time, standing, routes and provider-verified or tenant-asserted address. A work-account-only address is asserted by its tenant, with email_verified: false. Test users are marked test with expires_at and do not count against the user limit. Pass the returned next_cursor as cursor for the next page, until null. Use a row's id for set_end_user_standing or delete_end_user. Unredeemed invitations are on list_invitations. Choose the realm you address with environment. Production is the default.
Access and action metadata #
{
"name": "list_end_users",
"resource": "realm",
"tier": "observe",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"summary": "Each end user's opaque identifier, creation stamp, standing, routes, and provider-verified or tenant-asserted address, paged.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"idempotentHint": true
}
}
MCP catalog entry #
{
"name": "list_end_users",
"title": "List app users",
"tier": "observe",
"summary": "List an application's end users, paged: each user's id, creation time, standing, `routes` and provider-verified or tenant-asserted address. A work-account-only address is asserted by its tenant, with `email_verified: false`. Test users are marked `test` with `expires_at` and do not count against the user limit. Pass the returned `next_cursor` as `cursor` for the next page, until null. Use a row's id for `set_end_user_standing` or `delete_end_user`. Unredeemed invitations are on `list_invitations`. Choose the realm you address with `environment`. Production is the default.",
"owners": [
"ACS-L0-01",
"ACS-L0-08",
"PLD-L0-40"
],
"scenario": "ACS-L0-08"
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["application"] Additional properties: false |
| / |
Your account's application id from list_applications, not its name or label.Type: string |
| / |
Previous next_cursor; omit for the first page. A removed or expired user makes it invalid_request: start over.Type: string |
| / |
Users per page, 1 to 200; 50 where none is given. Type: integer Minimum: 1 Maximum: 200 |
| / |
Default production; development before create_environment is refused environment_not_created.Type: string Pattern: ^(development|production)$ |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","end_users","next_cursor"] Additional properties: false |
| / |
Required value: 1 |
| / |
Type: array |
| / |
Type: object Required fields: ["id","created_at","standing","routes","email","email_verified","test"] Additional properties: false |
| / |
Type: string |
| / |
Type: string |
| / |
Allowed values: ["active","suspended"] |
| / |
Type: array |
| / |
Type: string |
| / |
The user's address: a verified one, or, for a user who signed in by work account alone, the address the work-account tenant asserts, marked by email_source. Null where the user holds none.Type: ["string","null"] |
| / |
Whether the address is verified. A tenant-asserted address is verified only where the tenant's token stated the domain owner verified it; false otherwise. Type: boolean |
| / |
Present, tenant, where the address comes from the work-account tenant; email_verified is then true only where the tenant's token stated the domain owner verified it.Allowed values: ["tenant"] |
| / |
True for a test end user, a row add_test_end_users made, which holds one fixture-domain address, is signed in by a code read_test_signin_code returns, and counts as no user; false for every other row.Type: boolean |
| / |
A test end user alone: the instant from which the platform's expiry pass removes it. Absent on every other row. Type: string |
| / |
Type: ["string","null"] |
| / |
Type: string |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"application"
],
"properties": {
"application": {
"type": "string",
"description": "Your account's application `id` from `list_applications`, not its name or label."
},
"cursor": {
"type": "string",
"description": "Previous `next_cursor`; omit for the first page. A removed or expired user makes it `invalid_request`: start over."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Users per page, 1 to 200; 50 where none is given."
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "Default `production`; development before `create_environment` is refused `environment_not_created`."
}
},
"additionalProperties": false
},
"response": {
"type": "object",
"required": [
"contract_version",
"end_users",
"next_cursor"
],
"properties": {
"contract_version": {
"const": 1
},
"end_users": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"created_at",
"standing",
"routes",
"email",
"email_verified",
"test"
],
"properties": {
"id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"standing": {
"enum": [
"active",
"suspended"
]
},
"routes": {
"type": "array",
"items": {
"type": "string"
}
},
"email": {
"type": [
"string",
"null"
],
"description": "The user's address: a verified one, or, for a user who signed in by work account alone, the address the work-account tenant asserts, marked by `email_source`. Null where the user holds none."
},
"email_verified": {
"type": "boolean",
"description": "Whether the address is verified. A tenant-asserted address is verified only where the tenant's token stated the domain owner verified it; false otherwise."
},
"email_source": {
"enum": [
"tenant"
],
"description": "Present, `tenant`, where the address comes from the work-account tenant; `email_verified` is then true only where the tenant's token stated the domain owner verified it."
},
"test": {
"type": "boolean",
"description": "True for a test end user, a row `add_test_end_users` made, which holds one fixture-domain address, is signed in by a code `read_test_signin_code` returns, and counts as no user; false for every other row."
},
"expires_at": {
"type": "string",
"description": "A test end user alone: the instant from which the platform's expiry pass removes it. Absent on every other row."
}
},
"additionalProperties": false
}
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"detail": {
"type": "string"
}
},
"additionalProperties": false
}
}
Shared contracts #
- Refusals: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md