sign_in_test_end_user #
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/sign_in_test_end_user, 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 #
Sign one of your test end users in for the turnzero command, by `end_user` (its id or its label), with no mailbox and no browser. The call returns a line, `turnzero session`, in four forms: run once, it signs the user in and writes the session's cookie into a cookie jar file that `curl -b` reads, so the value never reaches this tool. The session lasts one hour, or until the test end user expires. Only test end users sign in this way. Development admits them from its creation; production needs a person's approval of `admit_test_end_users` first, and the `workforce` audience refuses the line, which runs under a minted token. The line needs turnzero 0.24.0 or later. Refused `test_end_users_not_admitted` where the line could not run, `not_test_end_user` for a user who is no unexpired test end user, and `test_end_users_disabled` while `TEST_END_USERS` is off. More: `read_documentation` with page /cloud/reference/actions/sign-in-test-end-user/.
More about this action #
The `environment` argument is required: `development` or `production`, the realm you address; the development realm exists only once `create_environment` has turned development on.
The line writes the jar into the folder above the one it runs in, under the end user's name; pass another `--out` to move it, outside any folder holding `package.json`, which the command refuses. The turnzero command's own call, on the HTTP action route with `delivery` as `command`, receives the session itself: the hostname, the end user, `expires_at`, and the cookie's name and value. No tool call carries `delivery`, and one that does is refused `local_route_required`. The command route refuses a minted token where the line is refused, a command below 0.24.0 `command_too_old`, a start past the address's hourly code starts `signin_code_rate_limited`, and a suspended test end user `user_suspended`. Every call is an action record, and no record carries the cookie's value.
Access and action metadata #
{
"name": "sign_in_test_end_user",
"resource": "realm",
"tier": "reversible",
"product": "cloud",
"summary": "Sign one test end user of one realm of your account's own application in for the turnzero command, `application`, `environment`, and `end_user` all required, the user by its identifier or its label. A tool's call, and any call without `delivery`, returns the line `turnzero session` in its four forms: run once, it signs the user in and writes the session's cookie into a cookie jar file `curl -b` reads, so the value passes through no tool. The turnzero command's own call on the HTTP action route, with `delivery` as `command`, returns the session: the hostname, the end user, `expires_at`, and the cookie's name and value, with no cookie set on the response. The session lasts one hour, or until the test end user's expiry, or the realm token's life where shorter. Admitted as `read_test_signin_code` is: the account's session, its account-wide token, or a token bounded to that application, `super_admin` widening it to no other account's application. The line is refused `test_end_users_not_admitted` under any credential on a production realm with no approval of `admit_test_end_users`, and under the workforce audience, where a minted token could not run it; on the command route a minted token is refused there alike. Refused `local_route_required` where `delivery` reaches any surface but the HTTP action route, `not_test_end_user` for a user who is not an unexpired test end user, `test_end_users_disabled` while `TEST_END_USERS` reads `off`, and `command_too_old` on the command route below turnzero 0.24.0. The command route is also refused `signin_code_rate_limited` past the address's hourly starts, and `signin_code_invalid` or `user_suspended` from the confirmation. Every call is one action record, and no record carries the cookie's value.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"openWorldHint": false
}
}
MCP catalog entry #
{
"name": "sign_in_test_end_user",
"title": "Sign in test app user",
"tier": "reversible",
"summary": "Sign one of your test end users in for the turnzero command, by `end_user` (its id or its label), with no mailbox and no browser. The call returns a line, `turnzero session`, in four forms: run once, it signs the user in and writes the session's cookie into a cookie jar file that `curl -b` reads, so the value never reaches this tool. The session lasts one hour, or until the test end user expires. Only test end users sign in this way. Development admits them from its creation; production needs a person's approval of `admit_test_end_users` first, and the `workforce` audience refuses the line, which runs under a minted token. The line needs turnzero 0.24.0 or later. Refused `test_end_users_not_admitted` where the line could not run, `not_test_end_user` for a user who is no unexpired test end user, and `test_end_users_disabled` while `TEST_END_USERS` is off. More: `read_documentation` with page /cloud/reference/actions/sign-in-test-end-user/.",
"owners": [
"ACS-L0-21",
"ACS-L0-20",
"ACS-L0-12",
"PLD-L0-94"
],
"scenario": "ACS-L0-21"
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["application","environment","end_user"] Additional properties: false |
| / |
The application id, from `list_applications`; one of your account's own. Type: string |
| / |
Required. The environment whose realm the test end user signs in to, `development` or `production`. Type: string Pattern: ^(development|production)$ |
| / |
The test end user: its opaque identifier, as `create_test_end_users` or `list_end_users` returned it, or its label, the local part of its address. A value in the identifier's form is read as one; any other is read as a label. Type: string |
| / |
Taken on the HTTP action route alone, from the turnzero command's `session` call: `command`, which makes the call return the session itself. The MCP tool has no `delivery` member, and a call that passes it there is refused `local_route_required`; a tool takes the line form instead. Type: string Allowed values: ["command"] HTTP action route only, never an MCP tool argument: true |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","application","environment","end_user"] Additional properties: false |
| / |
Required value: 1 |
| / |
With the state `awaiting_command`, on a call without `delivery`: nothing is signed in until the line runs. Required value: awaiting_command |
| / |
The application id. Type: string |
| / |
The environment whose realm the test end user signs in to. Type: string Pattern: ^(development|production)$ |
| / |
Type: object Required fields: ["id","label"] Additional properties: false |
| / |
The test end user's opaque identifier. Type: string |
| / |
The test end user's label, the local part of its address at the fixture domain. Type: string |
| / |
With the state `awaiting_command`: one line, for macOS and Linux, `turnzero session` with the application, the environment, the end user, and `--out`, the cookie jar file it writes in the folder above the one the line runs in. It carries `--force`, so a later run replaces that file. It ends with `--origin <origin>` when the responding origin is not the command's default. Run it once under this computer's token or TURNZERO_CLOUD_MINTED_TOKEN: it signs the user in and writes the cookie into the file in the form `curl -b` reads. It carries no credential, and it needs turnzero 0.24.0 or later. Type: string |
| / |
With the state `awaiting_command`: the same line for every Windows shell, with `turnzero.cmd` where its head says `turnzero`. Type: string |
| / |
With the state `awaiting_command`: the same line run through npx, `npx --no-update-notifier -y turnzero@<tag>` in place of `turnzero`, the tag `latest` on production's platform and `next` on every other, for a person or a job where the command is not installed. It is present exactly where `command` is. A tool runs `command_npx` only where `turnzero --version` responds and the bare line does not resolve in its shell. Where the command is not installed, a tool uses `deploy_files` within its caps; over them, or for the faster line, it takes the deploy skill's setup steps, never the npx line. A person or a job may run the npx line in place of the install. Type: string |
| / |
With the state `awaiting_command`: `command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx`. Type: string |
| / |
On the turnzero command's own call, with `delivery` as `command`: the session is open, and this answer alone carries its cookie. Required value: signed_in |
| / |
With `status` `signed_in`: the realm's hostname, the cookie's domain in the jar, the production environment's custom domain while its identifier span runs. Type: string |
| / |
With `status` `signed_in`: the session's expiry, as an ISO 8601 instant: one hour after the sign-in, or the test end user's own expiry where sooner, or the sign-in plus the realm token's life where that is shorter. Type: string |
| / |
With `status` `signed_in`: the session cookie the command writes into its jar, the value in this answer and in no record. Type: object Required fields: ["name","value","path","secure","http_only"] Additional properties: false |
| / |
The realm session cookie's name, `__Host-turnzero_cloud_realm`. Type: string |
| / |
The session's signed token, the cookie's value: a credential, returned once, written into the jar and into nothing else. Type: string |
| / |
The cookie's path, `/`. Type: string |
| / |
True: the cookie travels over https alone. Type: boolean |
| / |
True: no page script reads the cookie, which the jar marks as curl does. Type: boolean |
| / |
Type: string |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"application",
"environment",
"end_user"
],
"properties": {
"application": {
"type": "string",
"description": "The application id, from `list_applications`; one of your account's own."
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "Required. The environment whose realm the test end user signs in to, `development` or `production`."
},
"end_user": {
"type": "string",
"description": "The test end user: its opaque identifier, as `create_test_end_users` or `list_end_users` returned it, or its label, the local part of its address. A value in the identifier's form is read as one; any other is read as a label."
},
"delivery": {
"type": "string",
"enum": [
"command"
],
"x-wire-only": true,
"description": "Taken on the HTTP action route alone, from the turnzero command's `session` call: `command`, which makes the call return the session itself. The MCP tool has no `delivery` member, and a call that passes it there is refused `local_route_required`; a tool takes the line form instead."
}
},
"additionalProperties": false
},
"response": {
"type": "object",
"required": [
"contract_version",
"application",
"environment",
"end_user"
],
"properties": {
"contract_version": {
"const": 1
},
"state": {
"const": "awaiting_command",
"description": "With the state `awaiting_command`, on a call without `delivery`: nothing is signed in until the line runs."
},
"application": {
"type": "string",
"description": "The application id."
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "The environment whose realm the test end user signs in to."
},
"end_user": {
"type": "object",
"required": [
"id",
"label"
],
"properties": {
"id": {
"type": "string",
"description": "The test end user's opaque identifier."
},
"label": {
"type": "string",
"description": "The test end user's label, the local part of its address at the fixture domain."
}
},
"additionalProperties": false
},
"command": {
"type": "string",
"description": "With the state `awaiting_command`: one line, for macOS and Linux, `turnzero session` with the application, the environment, the end user, and `--out`, the cookie jar file it writes in the folder above the one the line runs in. It carries `--force`, so a later run replaces that file. It ends with `--origin <origin>` when the responding origin is not the command's default. Run it once under this computer's token or TURNZERO_CLOUD_MINTED_TOKEN: it signs the user in and writes the cookie into the file in the form `curl -b` reads. It carries no credential, and it needs turnzero 0.24.0 or later."
},
"command_windows": {
"type": "string",
"description": "With the state `awaiting_command`: the same line for every Windows shell, with `turnzero.cmd` where its head says `turnzero`."
},
"command_npx": {
"type": "string",
"description": "With the state `awaiting_command`: the same line run through npx, `npx --no-update-notifier -y turnzero@<tag>` in place of `turnzero`, the tag `latest` on production's platform and `next` on every other, for a person or a job where the command is not installed. It is present exactly where `command` is. A tool runs `command_npx` only where `turnzero --version` responds and the bare line does not resolve in its shell. Where the command is not installed, a tool uses `deploy_files` within its caps; over them, or for the faster line, it takes the deploy skill's setup steps, never the npx line. A person or a job may run the npx line in place of the install (PLD-L0-94)."
},
"command_npx_windows": {
"type": "string",
"description": "With the state `awaiting_command`: `command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx` (PLD-L0-94)."
},
"status": {
"const": "signed_in",
"description": "On the turnzero command's own call, with `delivery` as `command`: the session is open, and this answer alone carries its cookie."
},
"hostname": {
"type": "string",
"description": "With `status` `signed_in`: the realm's hostname, the cookie's domain in the jar, the production environment's custom domain while its identifier span runs."
},
"expires_at": {
"type": "string",
"description": "With `status` `signed_in`: the session's expiry, as an ISO 8601 instant: one hour after the sign-in, or the test end user's own expiry where sooner, or the sign-in plus the realm token's life where that is shorter."
},
"cookie": {
"type": "object",
"description": "With `status` `signed_in`: the session cookie the command writes into its jar, the value in this answer and in no record.",
"required": [
"name",
"value",
"path",
"secure",
"http_only"
],
"properties": {
"name": {
"type": "string",
"description": "The realm session cookie's name, `__Host-turnzero_cloud_realm`."
},
"value": {
"type": "string",
"description": "The session's signed token, the cookie's value: a credential, returned once, written into the jar and into nothing else."
},
"path": {
"type": "string",
"description": "The cookie's path, `/`."
},
"secure": {
"type": "boolean",
"description": "True: the cookie travels over https alone."
},
"http_only": {
"type": "boolean",
"description": "True: no page script reads the cookie, which the jar marks as curl does."
}
},
"additionalProperties": false
},
"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