--- title: "invite_end_user" description: "Generated reference for the management action invite_end_user: its description, access metadata, payload contract, and registration status." slug: /reference/actions/invite-end-user order: 57 visibility: public redirects_from: ["/reference/actions/issue-invitation","/reference/actions/revoke-invitation","/reference/actions/invitation"] --- # invite\_end\_user Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources). A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/actions/invite_end_user`, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool `tzcloud_invite_end_user`. **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 Issue or revoke an invitation to sign in\. Pass `email` to issue one, or its `invitation` id to revoke one, never both\. For an application's end user, pass `application`: the platform sends no email, so send the returned single\-use URL yourself\. Only a sign\-in with the invited verified address can redeem it, and the URL appears only in this answer\. An invitation is needed only when `configure_realm` sets creation to `invited`; it expires after `invitation_days`, 14 by default\. Without `application`, the platform operator invites a tzCloud builder and emails the URL, reported by `emailed`; `products` lists the access granted and always includes `tzcloud`\. Revoking an unredeemed invitation ends its URL\. An already redeemed invitation and the sign\-in it allowed stay unchanged\. ## More about this action With no `application`, the platform operator invites a builder to tzCloud itself, and `products` lists the products the redemption grants\. This form is refused `email_domain_undeliverable` when the address's domain accepts no mail\. With no `application`, a revocation ends an invitation of that builder sign\-in\. The `products` value is `["tzcloud"]` if omitted, and `["tzcloud", "tzteam"]` for an invitation that also grants tzTeam access\. The profiles go to the account the redemption creates, or to the existing account whose sign\-in with that address redeems the invitation for a product it lacks\. An optional `environment` \(`development` or `production`; absent, `production`\) chooses the realm you address; the development realm exists only once `create_environment` has turned development on\. The `products` argument: Optional, and for the builder form alone: the product profiles the invitation's redemption adds, as `read_account` lists them under `profiles[].product`\. The value `tzcloud` is always among them: `["tzcloud"]` if omitted, and `["tzcloud", "tzteam"]` for an invitation that also grants tzTeam access\. The profile's earlier spelling, `blueprint`, is accepted for `tzteam` during the rename\. The profiles are added to the account the redemption creates, or to the existing account whose sign\-in with the invited address redeems the invitation for a product it lacks\. The member is refused `invalid_request` where `application` is present, because an application's end user has no product profile\. `tzmesh` and `tztrack` are admitted by the vocabulary and refused `invalid_request` by the builder form: no invitation adds either profile\. The `invitation` argument: the invitation to revoke, and refused `invalid_request` beside `email` or `products`\. A revoked invitation is refused at redemption as an unrecognized invitation\. An invitation that was already redeemed is unchanged: the sign\-in it allowed remains, and the answer's `revoked_at` is null\. ## Access and action metadata ```json { "name": "invite_end_user", "resource": "realm", "tier": "reversible", "surface": "tzcloud", "product": "cloud", "summary": "Issue or revoke one invitation of a realm. A call with `email` mints one single-use invitation URL for that address, expiring after the configured interval. A call with `invitation` ends that invitation before its redemption by stamping it revoked; a revoked invitation is refused at redemption as an unrecognized invitation. With no application member either form is the builder realm's, admitted to super_admin alone. A builder invitation lists in `products` the product profiles its redemption adds — `tzcloud` alone if omitted, `tzteam` beside it for tzTeam access. They go to the account it creates or to the existing account whose sign-in redeems it.", "annotations": { "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false } } ``` ## MCP catalog entry ```json { "name": "invite_end_user", "title": "Send or revoke invitation", "tier": "reversible", "summary": "Issue or revoke an invitation to sign in. Pass `email` to issue one, or its `invitation` id to revoke one, never both. For an application's end user, pass `application`: the platform sends no email, so send the returned single-use URL yourself. Only a sign-in with the invited verified address can redeem it, and the URL appears only in this answer. An invitation is needed only when `configure_realm` sets creation to `invited`; it expires after `invitation_days`, 14 by default.\n\nWithout `application`, the platform operator invites a tzCloud builder and emails the URL, reported by `emailed`; `products` lists the access granted and always includes `tzcloud`. Revoking an unredeemed invitation ends its URL. An already redeemed invitation and the sign-in it allowed stay unchanged.", "owners": [ "ACS-L0-01", "ACS-L0-08", "PLD-L0-40", "ACB-L0-76", "ACB-L0-77" ], "scenario": "ACS-L0-08" } ``` ## request | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Required fields: \[\]
Additional properties: false
Retired members: act: Leave act out: pass email to issue an invitation, or invitation, its id, to revoke one\. | | /properties/application | The id of one of your applications \(see `list_applications`\); its manifest must declare the accounts service\. Omit it only if you are the platform operator: with no application, the act addresses the platform's own builder sign\-in and requires the `super_admin` grant\.

Type: string | | /properties/email | The address to invite, to issue an invitation\. One of `email` and `invitation` is required, and they are refused together\.

Type: string
Format: email | | /properties/invitation | The invitation's id, to revoke it before its redemption\.

Type: string | | /properties/environment | Optional\. The environment whose realm you address, `development` or `production`; absent, `production`\. Ignored when `application` is absent, because the platform's builder realm has no environment\.

Type: string
Pattern: ^\(development\|production\)$ | | /properties/products | Optional, to issue a builder invitation alone: the products its redemption grants, `tzcloud` always among them, `["tzcloud"]` when absent\. Refused with `invalid_request` when `application` is present, and for any product no invitation adds\.

Type: array
Minimum items: 1
uniqueItems: true | | /properties/products/items | Type: string | ## response | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Required fields: \["contract\_version","invitation"\]
Additional properties: false | | /properties/contract\_version | Required value: 1 | | /properties/invitation | The invitation: on an issue, its `id`, `email`, `url`, and `expires_at`; on a revocation, its `id` and `revoked_at`\.

Type: object
Required fields: \["id"\]
Additional properties: false | | /properties/invitation/properties/id | Type: string | | /properties/invitation/properties/email | Type: string | | /properties/invitation/properties/url | Type: string | | /properties/invitation/properties/expires\_at | Type: string | | /properties/invitation/properties/products | Only for a builder invitation: the products the redemption grants, as your request listed them, or `["tzcloud"]` when it listed none\.

Type: array | | /properties/invitation/properties/products/items | Type: string | | /properties/invitation/properties/revoked\_at | The revocation stamp; null where the invitation was already redeemed and the act changed nothing\.

Type: \["string","null"\] | | /properties/emailed | Only for a builder invitation: true when the platform emailed the URL to the invited address; false when the platform has no sender, the send failed or got no answer within its bound, or the platform's builder invitation window refused it\. A send with no answer within its bound is the one case in which `emailed` can read false for a message that left\. The invitation is created either way\.

Type: boolean | | /properties/detail | Type: string | ## Complete payload contract ```json { "request": { "type": "object", "required": [], "properties": { "application": { "type": "string", "description": "The id of one of your applications (see `list_applications`); its manifest must declare the accounts service. Omit it only if you are the platform operator: with no application, the act addresses the platform's own builder sign-in and requires the `super_admin` grant." }, "email": { "type": "string", "format": "email", "description": "The address to invite, to issue an invitation. One of `email` and `invitation` is required, and they are refused together." }, "invitation": { "type": "string", "description": "The invitation's id, to revoke it before its redemption." }, "environment": { "type": "string", "pattern": "^(development|production)$", "description": "Optional. The environment whose realm you address, `development` or `production`; absent, `production`. Ignored when `application` is absent, because the platform's builder realm has no environment." }, "products": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" }, "description": "Optional, to issue a builder invitation alone: the products its redemption grants, `tzcloud` always among them, `[\"tzcloud\"]` when absent. Refused with `invalid_request` when `application` is present, and for any product no invitation adds." } }, "additionalProperties": false, "x-retired": { "act": "Leave act out: pass email to issue an invitation, or invitation, its id, to revoke one." } }, "response": { "type": "object", "required": [ "contract_version", "invitation" ], "properties": { "contract_version": { "const": 1 }, "invitation": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "url": { "type": "string" }, "expires_at": { "type": "string" }, "products": { "type": "array", "items": { "type": "string" }, "description": "Only for a builder invitation: the products the redemption grants, as your request listed them, or `[\"tzcloud\"]` when it listed none (ACB-L0-77)." }, "revoked_at": { "type": [ "string", "null" ], "description": "The revocation stamp; null where the invitation was already redeemed and the act changed nothing (ACS-L0-08)." } }, "additionalProperties": false, "description": "The invitation: on an issue, its `id`, `email`, `url`, and `expires_at`; on a revocation, its `id` and `revoked_at`." }, "emailed": { "type": "boolean", "description": "Only for a builder invitation: true when the platform emailed the URL to the invited address; false when the platform has no sender, the send failed or got no answer within its bound, or the platform's builder invitation window refused it. A send with no answer within its bound is the one case in which `emailed` can read false for a message that left. The invitation is created either way (ACS-L0-08)." }, "detail": { "type": "string" } }, "additionalProperties": false } } ``` ## Shared contracts - [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy - [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/) - [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/) - [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes) - [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)