issue_invitation

{
  "name": "issue_invitation",
  "resource": "realm",
  "tier": "reversible",
  "summary": "Mint one single-use invitation URL for one named address, expiring after the configured interval; with no application member the builder realm's invitation, admitted to super_admin alone, naming in `products` the product profiles its redemption adds — `cloud` alone where absent, `blueprint` beside it for Turn Zero Blueprint access — to the account it creates or to the existing account whose sign-in redeems it.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": false
  }
}

{
  "name": "issue_invitation",
  "tier": "reversible",
  "summary": "Create an invitation for one email address to sign in to one of your applications. 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 — 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 where 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 no `application`, the platform operator invites a builder to Turn Zero Cloud itself, and `products` names the product profiles the redemption adds. The `products` value is `[\"cloud\"]` where absent, `[\"cloud\", \"blueprint\"]` for an invitation that also grants Turn Zero Blueprint access — to the account it creates, or to the existing account whose sign-in with that address redeems it for a product it lacks. An optional `environment` (`development` or `production`; absent, `production`) names the realm the call addresses, development's standing only once `create_environment` has turned development on.",
  "owners": [
    "ACS-L0-01",
    "ACS-L0-08",
    "PLD-L0-40",
    "ACB-L0-76",
    "ACB-L0-77"
  ],
  "scenario": "ACS-L0-08"
}

{
  "request": {
    "type": "object",
    "required": [
      "email"
    ],
    "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 invitation is to the platform's own builder sign-in and requires the `super_admin` grant."
      },
      "email": {
        "type": "string",
        "format": "email",
        "description": "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."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "Optional. The environment whose realm the call addresses, `development` or `production` (the accounts service PRD's realm statement); absent, `production`. Ignored where `application` is absent, because the builder realm has no environment."
      },
      "products": {
        "type": "array",
        "minItems": 1,
        "uniqueItems": true,
        "items": {
          "enum": [
            "cloud",
            "blueprint"
          ]
        },
        "description": "Optional, and the builder form's alone: the product profiles the invitation's redemption adds, as `read_account` names them under `profiles[].product` — `cloud` always among them, `[\"cloud\"]` where absent, `[\"cloud\", \"blueprint\"]` for an invitation that also grants Turn Zero Blueprint access. Added to the account the redemption creates, or to the existing account whose sign-in with the named address redeems the invitation for a product it lacks. Refused `invalid_request` where `application` is present: an application's end user holds no product profile."
      }
    },
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "invitation"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "invitation": {
        "type": "object",
        "required": [
          "id",
          "email",
          "url",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "expires_at": {
            "type": "string"
          },
          "products": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The builder form alone: the product profiles the redemption adds, as the request named them or `[\"cloud\"]` where it named none (ACB-L0-77)."
          }
        },
        "additionalProperties": false
      },
      "emailed": {
        "type": "boolean",
        "description": "The builder form alone: true where the platform emailed the URL to the invited address, false where the platform holds no sender, the send failed or had no answer within its bound, or the builder invitation window refused it. A send with no answer within its bound is the one case in which the member can read false for a message that left. The invitation stands either way (ACS-L0-08)."
      },
      "detail": {
        "type": "string"
      }
    },
    "additionalProperties": false
  }
}