--- title: "invitation" description: "Generated reference for the management action invitation: its description, access metadata, payload contract, and registration status." slug: /reference/actions/invitation order: 75 visibility: public redirects_from: ["/reference/actions/issue-invitation","/reference/actions/revoke-invitation"] --- # invitation Generated automatically from the [published contract sources](/reference/about#contract-sources). A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/actions/invitation`, 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 Issue or revoke an invitation to sign in to one of your applications, by `act`\. With `act: issue`, pass one `email` address: the call returns a single\-use URL that only a sign\-in with that verified address can redeem\. For one of your applications the platform sends no email, so you send the URL; for the platform operator's own builder invitation it emails the URL to the address and says so in `emailed`\. The URL appears in this response only\. An invitation is required only when the realm's creation mode is `invited` \(`configure_realm`\); with open creation, anyone may sign in without one\. It expires after the realm's `invitation_days`, 14 by default\. With `act: revoke`, pass the `invitation` id: its URL can no longer be redeemed, and an invitation already redeemed is unchanged\. More: `read_documentation` with page /cloud/reference/actions/invitation/\. ## More about this action With no `application`, the platform operator invites a builder to tzCloud itself, and `products` lists the product profiles the redemption adds\. This form is refused `email_domain_undeliverable` when the address's domain accepts no mail\. With no `application`, the `revoke` act ends an invitation of that builder sign\-in\. The `products` value is `["cloud"]` where absent, and `["cloud", "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 `cloud` is always among them: `["cloud"]` where absent, and `["cloud", "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\. The `invitation` argument: required with `act: revoke`, and refused `invalid_request` with `act: issue`\. So are `email` and `products` with `act: revoke`\. 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": "invitation", "resource": "realm", "tier": "reversible", "product": "cloud", "summary": "Issue or revoke one invitation of a realm, by `act`. `issue` mints one single-use invitation URL for one named address, expiring after the configured interval. `revoke` ends one named invitation before its redemption by stamping it revoked; a revoked invitation is refused at redemption as an unrecognized invitation. With no application member either act is the builder realm's, admitted to super_admin alone. A builder invitation lists in `products` the product profiles its redemption adds — `cloud` alone where absent, `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": "invitation", "title": "Send or revoke invitation", "tier": "reversible", "summary": "Issue or revoke an invitation to sign in to one of your applications, by `act`. With `act: issue`, pass one `email` address: the call returns a single-use URL that only a sign-in with that verified address can redeem. For one of your applications the platform sends no email, so you send the URL; for the platform operator's own builder invitation it emails the URL to the address and says so in `emailed`. The URL appears in this response only.\n\nAn invitation is required only when the realm's creation mode is `invited` (`configure_realm`); with open creation, anyone may sign in without one. It expires after the realm's `invitation_days`, 14 by default.\n\nWith `act: revoke`, pass the `invitation` id: its URL can no longer be redeemed, and an invitation already redeemed is unchanged. More: `read_documentation` with page /cloud/reference/actions/invitation/.", "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: \["act"\]
Additional properties: false | | /properties/act | `issue` creates an invitation for `email` and returns its single\-use URL; `revoke` ends, before its redemption, the invitation whose id `invitation` gives\.

Type: string
Allowed values: \["issue","revoke"\] | | /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 | Required to issue: the address the invitation is for\. The URL is redeemed only by a sign\-in whose provider\-verified address is this one; letter case is ignored\.

Type: string
Format: email | | /properties/invitation | Required to revoke: the invitation's id, as the `issue` act returned it\.

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 product profiles its redemption adds, `cloud` always among them, `["cloud"]` when absent\.

Type: array
Minimum items: 1
uniqueItems: true | | /properties/products/items | Allowed values: \["cloud","tzteam","blueprint"\] | ## 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: with `act: issue`, its `id`, `email`, `url`, and `expires_at`; with `act: revoke`, 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 product profiles the redemption adds, as your request listed them, or `["cloud"]` 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": [ "act" ], "properties": { "act": { "type": "string", "enum": [ "issue", "revoke" ], "description": "`issue` creates an invitation for `email` and returns its single-use URL; `revoke` ends, before its redemption, the invitation whose id `invitation` gives." }, "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": "Required to issue: the address the invitation is for. The URL is redeemed only by a sign-in whose provider-verified address is this one; letter case is ignored." }, "invitation": { "type": "string", "description": "Required to revoke: the invitation's id, as the `issue` act returned it." }, "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": { "enum": [ "cloud", "tzteam", "blueprint" ] }, "description": "Optional, to issue a builder invitation alone: the product profiles its redemption adds, `cloud` always among them, `[\"cloud\"]` when absent." } }, "additionalProperties": false }, "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 product profiles the redemption adds, as your request listed them, or `[\"cloud\"]` 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: with `act: issue`, its `id`, `email`, `url`, and `expires_at`; with `act: revoke`, 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](/reference/refusals): every refusal, by surface, with its cause and its remedy - [schemas/wire\_error\.schema\.json](/reference/sources/schemas/wire-error-schema) - [schemas/wire\_errors\.json](/reference/sources/schemas/wire-errors) - [schemas/action\_payloads\.json](/reference/sources/schemas/action-payloads) (includes shared shapes) - [management\_api\_contract\.md](/reference/sources/management-api-contract)