invite_end_user #

Generated automatically from the published 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 #

{
  "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 #

{
  "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 #

{
  "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: 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