mint_token

{
  "name": "mint_token",
  "resource": "token",
  "tier": "reversible",
  "summary": "Mint a token from the connected session: its scope (the account, or one application), an optional expiry and label, and the grants requested, each given only where the session holds it; the space grant `issues`, given by any session of the account, names one space the account holds in `space` and the `level` it reaches it at, `report`, `contribute`, or `owner`, its `label` required and naming the holder; the value is answered exactly once. A token carrying `issues` is minted for an account holding Turn Zero Blueprint alone, and otherwise refused `blueprint_required` with nothing minted. Where the token code form is served, a call naming `code_challenge` answers a one-time token code's line and no value, and the turnzero-cloud command's exchange under that code answers the value once.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": false
  }
}

{
  "name": "mint_token",
  "tier": "reversible",
  "summary": "Create an API token for unattended use — a script, a CI job. The token is bounded at minting to the whole account or to one application and never widens, carries only the grants you ask for from those this session holds, and cannot mint another token. Its value is answered once, in this response, and nowhere after; `list_tokens` shows tokens without values.",
  "owners": [
    "API-L0-05",
    "API-L0-17",
    "MAPI-14",
    "MAPI-12"
  ],
  "scenario": "API-L0-05"
}

{
  "request": {
    "type": "object",
    "required": [
      "scope_kind"
    ],
    "properties": {
      "scope_kind": {
        "enum": [
          "account",
          "application"
        ],
        "description": "`account` for a token that acts across the whole account, or `application` for one bounded to a single application."
      },
      "application": {
        "type": "string",
        "description": "Required where `scope_kind` is `application`: the application id the token is bounded to. Not accepted for an account-scoped token."
      },
      "grants": {
        "type": "array",
        "items": {
          "enum": [
            "destructive",
            "super_admin",
            "synthetic_seed_purge",
            "synthetic_estate",
            "publication",
            "feedback_queue",
            "issues"
          ]
        },
        "description": "Extra grants to carry, from `destructive`, `super_admin`, `synthetic_seed_purge`, `synthetic_estate`, `publication`, `feedback_queue`, and `issues`. This session must hold `destructive` and `super_admin` to give them. Only a session holding `super_admin` gives `synthetic_seed_purge`, `synthetic_estate`, `publication`, and `feedback_queue`; any session of the account gives `issues` with `space`, `level`, and `label`. At most one of the five narrow grants rides a token without `super_admin`. Neither `super_admin` nor a narrow grant is given on an application-scoped token (`grant_scope_refused`). Omitted, the token carries none and cannot perform destructive acts."
      },
      "space": {
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
        "description": "With the `issues` grant: the space the token reaches, one the account holds, as list_issue_spaces answers it."
      },
      "level": {
        "enum": [
          "report",
          "contribute",
          "owner"
        ],
        "description": "With the `issues` grant: `report` files, follows, checks, and reads; `contribute` also works issues; `owner` reaches every act the relay carries."
      },
      "expires_in_days": {
        "type": "integer",
        "minimum": 1,
        "maximum": 3650,
        "description": "Days until the token expires, 1 to 3650. Omitted, the token does not expire."
      },
      "label": {
        "type": "string",
        "maxLength": 120,
        "minLength": 1,
        "description": "A label for the token, 1 to 120 characters, shown by `list_tokens`; required with the `issues` grant, naming the holder, in printable characters and unlike every unrevoked token's label for the same space."
      },
      "code_challenge": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{43}$",
        "description": "The S256 challenge the turnzero-cloud command prints, 43 base64url characters. Named, the call mints a one-time token code in place of a token and answers the line that presents it, never a value. Answered only where the token code form is served."
      },
      "authorized_computer": {
        "type": "boolean",
        "description": "True for the token the turnzero-cloud command keeps on the computer whose challenge the call names: account-scoped, at most 30 days, 30 where `expires_in_days` is absent, and marked in `list_tokens`. Answered only where the token code form is served."
      },
      "code_verifier": {
        "type": "string",
        "x-wire-only": true,
        "description": "The exchange's one member, sent by the turnzero-cloud command on the HTTP action route under the token code its line carries: the verifier whose S256 challenge the mint named. No tool carries it. Answered only where the token code form is served."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "token"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "token": {
        "type": "object",
        "required": [
          "scope_kind",
          "application",
          "grants",
          "label",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "scope_kind": {
            "enum": [
              "account",
              "application"
            ]
          },
          "application": {
            "type": [
              "string",
              "null"
            ]
          },
          "grants": {
            "type": "array",
            "items": {
              "enum": [
                "destructive",
                "super_admin",
                "synthetic_seed_purge",
                "synthetic_estate",
                "publication",
                "feedback_queue",
                "issues"
              ]
            }
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "authorized_computer": {
            "type": "boolean",
            "description": "Whether the token is an authorized computer's: on the answer of a mint naming `code_challenge` and on the exchange's answer. Answered only where the token code form is served."
          },
          "space": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
            "description": "The space the issues grant names; present on a token that carries the grant alone."
          },
          "level": {
            "enum": [
              "report",
              "contribute",
              "owner"
            ],
            "description": "The level the issues grant reaches its space at: report, contribute, or owner; present on a token that carries the grant alone."
          },
          "created_at": {
            "type": "string"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": false
      },
      "value": {
        "type": "string",
        "description": "The token's value, answered once: by a mint naming no `code_challenge`, and by the exchange the turnzero-cloud command makes under a token code. A mint naming `code_challenge` answers none."
      },
      "state": {
        "const": "awaiting_command",
        "description": "On the answer of a mint naming `code_challenge`: the token code is minted and its line has yet to run. Answered only where the token code form is served."
      },
      "command": {
        "type": "string",
        "description": "On the answer of a mint naming `code_challenge`: one line, for macOS and Linux, that pipes the one-time token code to the turnzero-cloud command, `echo <code> | npx -y <origin>/packages/turnzero-cloud-<version>.tgz <subcommand>`. It takes one of two forms, an authorized computer's where `authorized_computer` is true and the person's otherwise, with `--origin <origin>` where the answering origin is not the command's default. A tool runs the first; the person runs the second in a terminal outside the AI tool. It is a credential until `expires_at`. Answered only where the token code form is served."
      },
      "command_windows": {
        "type": "string",
        "description": "On the answer of a mint naming `code_challenge`: the same line for every Windows shell, with `npx.cmd` where its head says `npx`. Answered only where the token code form is served."
      },
      "expires_at": {
        "type": "string",
        "description": "On the answer of a mint naming `code_challenge`: when the token code stops serving, as an ISO 8601 instant, the served `token_code_seconds` after the call and never past the minting session's expiry. A line run after it is refused `token_code_refused`. Answered only where the token code form is served."
      },
      "detail": {
        "type": "string",
        "description": "On the answer of a mint naming `code_challenge`: that the line is a credential until `expires_at`, to run once as given and paste into nothing but the terminal that runs it, and who runs it. Answered only where the token code form is served."
      }
    },
    "additionalProperties": false
  }
}