test_end_users #
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/test_end_users, with a bearer credential and the action's payload as the JSON body.
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 #
Create or remove test end users on your application's sign-in realm, by act, to test sign-in with no person and no mailbox.
With act: create, pass application, environment, and one to twenty labels: each becomes an end user with the verified address <label>@synthetic.turnzero.ai, which receives no mail, removed 48 hours after its creation. Sign one in at the test sign-in page with its address, read its code with read_test_signin_code, and type the code; the session is real, and your code runs unchanged. On production, a minted token needs an approval of admit_test_end_users.
With act: delete, pass application, environment, and end_users or all: true. Each removal ends the user's sessions on every router within sixty seconds. With act: withdraw, pass application alone: the call ends the production realm's admission and removes every test end user that realm has. More: read_documentation with page /cloud/reference/actions/test-end-users/.
More about this action #
Without an approval of admit_test_end_users, only your session creates test end users on production, while the application has no development environment. Under the workforce audience, only your session creates them. The create act is refused test_end_users_not_admitted where the realm or your credential is not admitted, and test_end_users_ceiling_reached past twenty on the realm or fifty created within the hour.
The environment argument is required: pass development or production, the environment whose realm you address. The development realm exists only after create_environment has turned development on.
The development realm accepts test end users from its creation. On an application with no development environment, your account's session can create them on production with no approval, and create_environment later removes them. Under the workforce audience, only your account's session can create them, in either environment. A minted token is refused there, even after an approval.
The call returns test_signin_page, the realm's test sign-in page. For each label it returns the user's id, label, email, expires_at, and created. Where an unexpired test end user already has a label, the call returns that user with created false and creates nothing, so a repeat is safe. Where the test end user with a label has expired, the call removes it and creates it afresh.
Test end users count toward no user count or limit. Where the call is refused test_end_users_not_admitted, the refusal's detail gives the remedy. The call is also refused not_test_end_user for a label whose address belongs to a real end user, and test_end_users_disabled while the platform's TEST_END_USERS setting is off.
The labels argument takes one to twenty labels. Each label is the local part of a test end user's address at the fixture domain synthetic.turnzero.ai. A label is three to forty characters: a lowercase letter, then lowercase letters, digits, and hyphens. A label whose address another end user of the realm has is refused 409 not_test_end_user.
The delete act removes test end users at once, passing end_users, their ids, up to twenty, or all: true. The environment argument is required: development or production, the realm you address. The call creates no pending action and needs no approval, because a test end user has no person's data. Each removal also deletes the user's held codes and ends the sign-ins they could still confirm. The call is refused whole with not_test_end_user, removing nothing, where any listed user is not a test end user of that realm; remove a real end user with delete_end_user.
The withdraw act ends the admission of test end users on your application's production realm and removes every test end user that realm has, as the delete act removes them. No approval is needed. Where no approval exists, the call withdraws nothing and still removes any test end user the realm has. It returns withdrawn, true where an admission was ended, and removed, the ids of the test end users removed.
The delete and withdraw acts work while the platform's TEST_END_USERS setting is off, so you can always clean up. A member another act takes is refused invalid_request by name: labels is the create act's alone, end_users and all the delete act's, and environment the create and delete acts'.
Access and action metadata #
{
"name": "test_end_users",
"resource": "realm",
"tier": "reversible",
"product": "cloud",
"summary": "Create, delete, or withdraw the test end users of one realm of your account's own application, by `act`. `create` makes up to twenty, `application` and `environment` both required. Each is a user row holding one verified `email` identity `<label>@synthetic.turnzero.ai`, expiring 48 hours after its creation, and counted as no user. It signs in through the realm's own emailed-code route, its code held for `read_test_signin_code` and never sent. For a label an unexpired test end user of the realm holds, the call returns that user unchanged with `created` false, so a retry creates nothing. A label whose row has expired is removed and created afresh. On a production realm with no approval of `admit_test_end_users` it admits the account's session alone, and only while the application has no development environment. Refused `test_end_users_not_admitted` there under any minted token, on that realm once development exists, and under any minted token in either environment of a workforce application. Refused `test_end_users_ceiling_reached` past twenty unexpired test end users on the realm or fifty created by the application's realms within the hour. Refused `not_test_end_user` for a label whose address another end user of the realm holds, and `test_end_users_disabled` while the control plane's `TEST_END_USERS` setting reads `off`. `delete` removes test end users at once, with no pending action, `application` and `environment` both required and either `end_users` or `all` true: each removal ends the user's rows, identities, and sessions, writes the user revocation row the routers sync, deletes the user's held codes, and takes the live tickets they were started under. Refused whole `not_test_end_user` where any named user is not a test end user of the realm. `withdraw` ends the production realm's admission of test end users, `application` alone, and removes every test end user of that realm as `delete` removes one. Where it withdraws or removes anything, the call writes one info line to the control plane's stream, giving the application and no address. Where no approval exists, the call withdraws nothing and still removes any test end user the realm holds. `delete` and `withdraw` are admitted while `TEST_END_USERS` reads `off`, so an operator's stop strands no test end user.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": false
}
}
MCP catalog entry #
{
"name": "test_end_users",
"title": "Create or remove test app users",
"tier": "reversible",
"summary": "Create or remove test end users on your application's sign-in realm, by `act`, to test sign-in with no person and no mailbox.\n\nWith `act: create`, pass `application`, `environment`, and one to twenty `labels`: each becomes an end user with the verified address `<label>@synthetic.turnzero.ai`, which receives no mail, removed 48 hours after its creation. Sign one in at the test sign-in page with its address, read its code with `read_test_signin_code`, and type the code; the session is real, and your code runs unchanged. On production, a minted token needs an approval of `admit_test_end_users`.\n\nWith `act: delete`, pass `application`, `environment`, and `end_users` or `all: true`. Each removal ends the user's sessions on every router within sixty seconds. With `act: withdraw`, pass `application` alone: the call ends the production realm's admission and removes every test end user that realm has. More: `read_documentation` with page /cloud/reference/actions/test-end-users/.",
"owners": [
"ACS-L0-21",
"ACS-L0-20",
"PLD-L0-40",
"ACS-L0-06"
],
"scenario": "ACS-L0-21"
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["act","application"] Additional properties: false Retired members: expires_in_days: Each test end user lasts 48 hours from its creation, one fixed lifetime: call again without expires_in_days. |
| / |
create makes test end users from labels; delete removes the end_users named, or all; withdraw ends the production realm's admission and removes every test end user of that realm.Type: string Allowed values: ["create","delete","withdraw"] |
| / |
The application id, from list_applications; one of your account's own.Type: string |
| / |
Required to create and to delete: the environment whose realm you address, development or production. Refused with act: withdraw, which addresses production.Type: string Pattern: ^(development|production)$ |
| / |
Required to create, one to twenty: each the local part of a test end user's address at the fixture domain synthetic.turnzero.ai. A label an unexpired test end user holds returns that user unchanged; one whose address another end user holds is refused 409 not_test_end_user.Type: array Minimum items: 1 Maximum items: 20 |
| / |
Type: string Pattern: ^[a-z][a-z0-9-]{2,39}$ |
| / |
To delete: the test end users to remove, by opaque identifier; one of end_users and all is required, and never both. Any identifier that is not a test end user of the realm refuses the whole request 409 not_test_end_user, and nothing is removed.Type: array Minimum items: 1 Maximum items: 20 |
| / |
Type: string |
| / |
To delete every test end user of the realm; one of end_users and all is required, and never both.Required value: true |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","realm","application"] Additional properties: false |
| / |
Required value: 1 |
| / |
The realm identifier: the application id for production, <id>:development for development.Type: string |
| / |
Type: string |
| / |
With act: create and act: delete: the environment whose realm the call addressed.Type: string Pattern: ^(development|production)$ |
| / |
With act: create: The realm's test sign-in page, /__account/signin/test on the environment's hostname, which offers the emailed-code form to a test end user on every admitting realm with a non-empty route set.Type: string |
| / |
With act: create: one entry per label, in the request's order.Type: array Minimum items: 1 Maximum items: 20 |
| / |
Type: object Required fields: ["id","label","email","expires_at","created"] Additional properties: false |
| / |
The test end user's opaque identifier, the one list_end_users returns.Type: string |
| / |
Type: string |
| / |
<label>@synthetic.turnzero.ai, the verified address the user signs in with.Type: string |
| / |
The instant from which the platform's expiry pass removes the user, within ten minutes. Type: string |
| / |
True where this call created the row, false where an unexpired test end user already held the label and was returned unchanged. Type: boolean |
| / |
With act: delete and act: withdraw: the identifiers of the test end users removed, each with its identities, sessions, held codes, and live tickets; empty where none was found.Type: array |
| / |
Type: string |
| / |
With act: withdraw: True where an admission was in place and was ended; false where the realm did not admit test end users.Type: boolean |
| / |
Type: string |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"act",
"application"
],
"properties": {
"act": {
"type": "string",
"enum": [
"create",
"delete",
"withdraw"
],
"description": "`create` makes test end users from `labels`; `delete` removes the `end_users` named, or `all`; `withdraw` ends the production realm's admission and removes every test end user of that realm."
},
"application": {
"type": "string",
"description": "The application id, from `list_applications`; one of your account's own."
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "Required to create and to delete: the environment whose realm you address, `development` or `production`. Refused with `act: withdraw`, which addresses production."
},
"labels": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{2,39}$"
},
"description": "Required to create, one to twenty: each the local part of a test end user's address at the fixture domain `synthetic.turnzero.ai`. A label an unexpired test end user holds returns that user unchanged; one whose address another end user holds is refused 409 `not_test_end_user`."
},
"end_users": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "string"
},
"description": "To delete: the test end users to remove, by opaque identifier; one of `end_users` and `all` is required, and never both. Any identifier that is not a test end user of the realm refuses the whole request 409 `not_test_end_user`, and nothing is removed."
},
"all": {
"const": true,
"description": "To delete every test end user of the realm; one of `end_users` and `all` is required, and never both."
}
},
"additionalProperties": false,
"x-retired": {
"expires_in_days": "Each test end user lasts 48 hours from its creation, one fixed lifetime: call again without expires_in_days."
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"realm",
"application"
],
"properties": {
"contract_version": {
"const": 1
},
"realm": {
"type": "string",
"description": "The realm identifier: the application id for production, `<id>:development` for development."
},
"application": {
"type": "string"
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "With `act: create` and `act: delete`: the environment whose realm the call addressed."
},
"test_signin_page": {
"type": "string",
"description": "With `act: create`: The realm's test sign-in page, `/__account/signin/test` on the environment's hostname, which offers the emailed-code form to a test end user on every admitting realm with a non-empty route set."
},
"test_end_users": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"description": "With `act: create`: one entry per label, in the request's order.",
"items": {
"type": "object",
"required": [
"id",
"label",
"email",
"expires_at",
"created"
],
"properties": {
"id": {
"type": "string",
"description": "The test end user's opaque identifier, the one `list_end_users` returns."
},
"label": {
"type": "string"
},
"email": {
"type": "string",
"description": "`<label>@synthetic.turnzero.ai`, the verified address the user signs in with."
},
"expires_at": {
"type": "string",
"description": "The instant from which the platform's expiry pass removes the user, within ten minutes."
},
"created": {
"type": "boolean",
"description": "True where this call created the row, false where an unexpired test end user already held the label and was returned unchanged."
}
},
"additionalProperties": false
}
},
"removed": {
"type": "array",
"items": {
"type": "string"
},
"description": "With `act: delete` and `act: withdraw`: the identifiers of the test end users removed, each with its identities, sessions, held codes, and live tickets; empty where none was found."
},
"withdrawn": {
"type": "boolean",
"description": "With `act: withdraw`: True where an admission was in place and was ended; false where the realm did not admit test end users."
},
"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