invitation #
Generated automatically from the published 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 #
{
"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 #
{
"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 |
| / |
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"] |
| / |
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 |
| / |
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 |
| / |
Required to revoke: the invitation's id, as the issue act returned it.Type: string |
| / |
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)$ |
| / |
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 |
| / |
Allowed values: ["cloud","tzteam","blueprint"] |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","invitation"] Additional properties: false |
| / |
Required value: 1 |
| / |
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 |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Only for a builder invitation: the product profiles the redemption adds, as your request listed them, or ["cloud"] when it listed none.Type: array |
| / |
Type: string |
| / |
The revocation stamp; null where the invitation was already redeemed and the act changed nothing. Type: ["string","null"] |
| / |
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 |
| / |
Type: string |
Complete payload contract #
{
"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: 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