SetupLink

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/tracetail-io/json-schema/tracetail-io-setup-link-schema.json",
  "title": "SetupLink",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/tracetail-io-openapi.json#/components/schemas/SetupLink",
  "type": "object",
  "required": [
    "id",
    "status",
    "setupUrl",
    "domains",
    "expiresAt",
    "next"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^sl_[0-9a-f]{32}$",
      "description": "The setup link's id."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "completed",
        "delivered",
        "expired"
      ],
      "description": "delivered: the keys were handed over (in this response, or an earlier one)."
    },
    "setupUrl": {
      "type": "string",
      "format": "uri",
      "description": "The page to give the person."
    },
    "domains": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the person, then the agent, runs out of time."
    },
    "next": {
      "type": "string",
      "description": "What to do next, in words."
    },
    "account": {
      "type": "object",
      "required": [
        "email",
        "paidUsage"
      ],
      "properties": {
        "email": {
          "type": "string",
          "description": "Masked (j***@example.com), for the person to check the account is theirs."
        },
        "paidUsage": {
          "type": "boolean",
          "description": "Metered usage billing is active."
        },
        "billingExempt": {
          "type": "boolean",
          "description": "When true, identification requests are unlimited and free."
        }
      },
      "description": "With the keys: the account they belong to."
    },
    "apiKeys": {
      "type": "array",
      "description": "With the keys, once: one per domain. apiKey is null where the account already had a key for it.",
      "items": {
        "type": "object",
        "required": [
          "domain",
          "apiKey"
        ],
        "properties": {
          "domain": {
            "type": "string"
          },
          "apiKey": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^tt_[0-9a-f]{64}$"
          }
        }
      }
    },
    "serverKey": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^tts_[0-9a-f]{64}$",
      "description": "With the keys, once, if requested and the account was created through the link (an existing account creates its own)."
    }
  }
}