{
  "openapi": "3.1.0",
  "info": {
    "title": "Femtoport Management API",
    "version": "2026-07-02",
    "description": "Stable API used by the Femtoport management console and automation clients."
  },
  "servers": [
    {
      "url": "https://manage.femtoport.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "tags": [
    {
      "name": "platform-admin",
      "description": "Operator-only; requires platform-admin session. 403 otherwise."
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "cookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "__Host-femtoport_session",
        "description": "Browser session cookie. Session-only operations reject machine kpm_ bearer tokens with 403 Forbidden."
      }
    },
    "schemas": {
      "APIKeyCreateRequest": {
        "type": "object",
        "required": [
          "label"
        ],
        "properties": {
          "label": {
            "type": "string",
            "maxLength": 80
          }
        }
      },
      "APIKeyCreateResponse": {
        "type": "object",
        "required": [
          "token_id",
          "workspace_id",
          "kind",
          "label",
          "role",
          "created_at",
          "is_current",
          "api_key"
        ],
        "properties": {
          "token_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "kind": {
            "const": "machine"
          },
          "label": {
            "type": "string"
          },
          "role": {
            "enum": [
              "owner",
              "admin",
              "member",
              "viewer"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "is_current": {
            "type": "boolean"
          },
          "api_key": {
            "type": "string",
            "description": "Plaintext kpm_ token returned once."
          }
        }
      },
      "AccountDeleteRequestResponse": {
        "type": "object",
        "required": [
          "challenge_id"
        ],
        "properties": {
          "challenge_id": {
            "type": "string"
          }
        }
      },
      "AccountDeleteConfirmRequest": {
        "type": "object",
        "required": [
          "challenge_id",
          "code"
        ],
        "properties": {
          "challenge_id": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "pattern": "^[0-9]{8}$"
          }
        }
      },
      "AccountExport": {
        "type": "object",
        "required": [
          "generated_at",
          "user",
          "legal_acceptances",
          "workspaces",
          "tunnels",
          "custom_domains",
          "tls_advanced_interest",
          "credit_grants",
          "usage_summary",
          "audit_events",
          "audit_truncated"
        ],
        "properties": {
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "user": {
            "$ref": "#/components/schemas/AccountExportUser"
          },
          "workspaces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccountExportWorkspace"
            }
          },
          "tunnels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccountExportTunnel"
            }
          },
          "custom_domains": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccountExportCustomDomain"
            }
          },
          "tls_advanced_interest": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccountExportTLSInterest"
            }
          },
          "credit_grants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccountExportCreditGrant"
            }
          },
          "usage_summary": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccountExportUsageSummary"
            }
          },
          "audit_events": {
            "type": "array",
            "maxItems": 10000,
            "items": {
              "$ref": "#/components/schemas/AccountExportAuditEvent"
            }
          },
          "audit_truncated": {
            "type": "boolean"
          },
          "legal_acceptances": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccountExportLegalAcceptance"
            }
          }
        }
      },
      "AccountExportUser": {
        "type": "object",
        "required": [
          "user_id",
          "email",
          "status",
          "created_at"
        ],
        "properties": {
          "user_id": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "registered_at": {
            "type": "string",
            "format": "date-time"
          },
          "public_referral_code": {
            "type": "string"
          },
          "referred_by_user_id": {
            "type": "string"
          }
        }
      },
      "AccountExportWorkspace": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "status",
          "role",
          "created_at"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AccountExportTunnel": {
        "type": "object",
        "required": [
          "tunnel_id",
          "workspace_id",
          "sni",
          "backend_mode",
          "target",
          "enabled",
          "created_at",
          "archived"
        ],
        "properties": {
          "tunnel_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "sni": {
            "type": "string"
          },
          "backend_mode": {
            "type": "string",
            "enum": [
              "proxy",
              "static",
              "ssh",
              "files",
              "vnc"
            ]
          },
          "target": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "archived": {
            "type": "boolean"
          },
          "archived_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AccountExportCustomDomain": {
        "type": "object",
        "required": [
          "domain_id",
          "ownership_status",
          "workspace_id",
          "hostname",
          "alias_hostname",
          "enabled",
          "dns_status",
          "cert_status",
          "route_status",
          "notification_status",
          "created_by_user_id",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "ownership_status": {
            "type": "string",
            "enum": [
              "verifying",
              "preparing",
              "verified",
              "ending",
              "removed",
              "review_required"
            ],
            "description": "Domain connection progress. Preparing means DNS ownership was proved and a safe handoff is in progress."
          },
          "ready_after": {
            "type": "string",
            "format": "date-time",
            "description": "Earliest next handoff check; fresh DNS proof and certificate readiness are still required."
          },
          "domain_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "hostname": {
            "type": "string"
          },
          "alias_hostname": {
            "type": "string"
          },
          "desired_tunnel_id": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "dns_status": {
            "type": "string"
          },
          "cert_status": {
            "type": "string"
          },
          "route_status": {
            "type": "string"
          },
          "notification_status": {
            "type": "string"
          },
          "created_by_user_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AccountExportTLSInterest": {
        "type": "object",
        "required": [
          "interest_id",
          "email",
          "user_id",
          "workspace_id",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "interest_id": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "user_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "tunnel_id": {
            "type": "string"
          },
          "source_ip": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AccountExportCreditGrant": {
        "type": "object",
        "required": [
          "workspace_id",
          "kind",
          "delta_bytes",
          "created_at"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "delta_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "new_entitled_until": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AccountExportUsageSummary": {
        "type": "object",
        "required": [
          "tunnel_id",
          "bytes_in",
          "bytes_out",
          "basis"
        ],
        "properties": {
          "tunnel_id": {
            "type": "string"
          },
          "bytes_in": {
            "type": "integer",
            "format": "int64"
          },
          "bytes_out": {
            "type": "integer",
            "format": "int64"
          },
          "basis": {
            "type": "string",
            "description": "Plain-language statement of what these figures are computed from."
          }
        }
      },
      "AccountExportAuditEvent": {
        "type": "object",
        "properties": {
          "log_id": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "actor_user_id": {
            "type": "string"
          },
          "actor_token_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "detail": {
            "type": "object",
            "additionalProperties": true
          },
          "source_ip": {
            "type": "string"
          }
        }
      },
      "CustomDomain": {
        "type": "object",
        "required": [
          "domain_id",
          "ownership_status",
          "workspace_id",
          "hostname",
          "alias_id",
          "alias_hostname",
          "enabled",
          "cert_source",
          "dns_status",
          "cert_status",
          "route_status",
          "notification_status",
          "created_by_user_id",
          "created_at",
          "updated_at",
          "verification_token",
          "subdomain_cname_value",
          "apex_txt_name",
          "apex_txt_value",
          "apex_a_values",
          "apex_aaaa_values",
          "management_url"
        ],
        "properties": {
          "ownership_status": {
            "type": "string",
            "enum": ["verifying", "preparing", "verified", "ending", "removed", "review_required"],
            "description": "Domain connection progress. Preparing means DNS ownership was proved and a safe handoff is in progress."
          },
          "ready_after": {
            "type": "string",
            "format": "date-time",
            "description": "Earliest next handoff check; fresh DNS proof and certificate readiness are still required."
          },
          "domain_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "hostname": {
            "type": "string"
          },
          "alias_id": {
            "type": "string"
          },
          "alias_hostname": {
            "type": "string"
          },
          "desired_tunnel_id": {
            "type": "string"
          },
          "desired_tunnel_sni": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "cert_source": {
            "type": "string",
            "enum": [
              "cert_worker",
              "agent_managed_acme"
            ],
            "description": "cert_worker: edge-terminated, Femtoport issues the cert. agent_managed_acme: end-to-end, the customer's agent holds the cert for the customer-owned hostname (free)."
          },
          "dns_status": {
            "type": "string",
            "enum": [
              "pending",
              "verified",
              "failed"
            ]
          },
          "cert_status": {
            "type": "string",
            "enum": [
              "pending",
              "active",
              "failed",
              "renewing"
            ]
          },
          "route_status": {
            "type": "string",
            "enum": [
              "inactive",
              "status_page",
              "active"
            ]
          },
          "notification_status": {
            "type": "string",
            "enum": [
              "pending",
              "sent",
              "failed"
            ]
          },
          "dns_verified_at": {
            "type": "string",
            "format": "date-time"
          },
          "cert_ready_at": {
            "type": "string",
            "format": "date-time"
          },
          "route_ready_at": {
            "type": "string",
            "format": "date-time"
          },
          "next_dns_check_at": {
            "type": "string",
            "format": "date-time"
          },
          "next_cert_check_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_error": {
            "type": "string"
          },
          "created_by_user_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "verification_token": {
            "type": "string"
          },
          "subdomain_cname_value": {
            "type": "string"
          },
          "apex_txt_name": {
            "type": "string"
          },
          "apex_txt_value": {
            "type": "string"
          },
          "apex_a_values": {
            "type": "array",
            "description": "IPv4 edge addresses; the customer creates one A record per value.",
            "items": {
              "type": "string"
            }
          },
          "apex_aaaa_values": {
            "type": "array",
            "description": "IPv6 edge addresses; the customer creates one AAAA record per value. Either family satisfies apex verification.",
            "items": {
              "type": "string"
            }
          },
          "management_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "CustomDomainListResponse": {
        "type": "object",
        "required": [
          "domains"
        ],
        "properties": {
          "domains": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomDomain"
            }
          }
        }
      },
      "CustomDomainCreateRequest": {
        "type": "object",
        "required": [
          "hostname"
        ],
        "properties": {
          "hostname": {
            "type": "string"
          },
          "desired_tunnel_id": {
            "type": "string"
          }
        }
      },
      "CustomDomainPatchRequest": {
        "type": "object",
        "properties": {
          "desired_tunnel_id": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "Tunnel": {
        "type": "object",
        "required": [
          "tunnel_id",
          "workspace_id",
          "sni",
          "public_url",
          "tls_mode",
          "cert_source",
          "backend_mode",
          "target",
          "enabled",
          "created_by_user_id",
          "created_at",
          "updated_at",
          "name"
        ],
        "properties": {
          "tunnel_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "sni": {
            "type": "string"
          },
          "public_url": {
            "type": "string",
            "format": "uri"
          },
          "tls_mode": {
            "enum": [
              "terminated",
              "passthrough"
            ]
          },
          "cert_source": {
            "type": "string"
          },
          "backend_mode": {
            "type": "string",
            "enum": [
              "proxy",
              "static",
              "ssh",
              "files",
              "vnc"
            ]
          },
          "target": {
            "type": "string"
          },
          "agent_config": {
            "$ref": "#/components/schemas/AgentConfig"
          },
          "enabled": {
            "type": "boolean"
          },
          "created_by_user_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "bytes_in_total": {
            "type": "integer",
            "format": "int64"
          },
          "bytes_out_total": {
            "type": "integer",
            "format": "int64"
          },
          "last_observed_at": {
            "type": "string",
            "format": "date-time"
          },
          "agent_router_id": {
            "type": "string"
          },
          "agent_started_at": {
            "type": "string",
            "format": "date-time"
          },
          "agent_last_seen": {
            "type": "string",
            "format": "date-time"
          },
          "transport_mode": {
            "enum": [
              "plain",
              "inner_tls"
            ],
            "description": "Live agent session transport mode. inner_tls means the agent is using pinned inner TLS because the outer network performs TLS inspection."
          },
          "agent_token": {
            "type": "string",
            "description": "One-time plaintext kpt_ token returned on tunnel creation or token issue only."
          },
          "custom_domains": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomDomain"
            }
          },
          "e2e_enabled_at": {
            "type": "string",
            "format": "date-time",
            "description": "Set when the tunnel is on passthrough + agent-managed ACME (end-to-end TLS); empty on the shared wildcard."
          },
          "e2e_available": {
            "type": "boolean",
            "description": "Whether the workspace holds the paid e2e_tls feature grant. Computed per-request by list/get, not a stored column."
          },
          "e2e_blocked_by_agent_os": {
            "type": "string",
            "description": "Platform of a recently-connected agent that cannot terminate TLS itself (e.g. esp-idf), explaining why the E2E toggle would fail. Absent when nothing blocks it."
          },
          "public_connections_per_ip_per_minute": {
            "type": "integer",
            "minimum": 0,
            "maximum": 60000,
            "default": 0,
            "description": "Optional new-connection limit per source IP per hostname per minute. Zero disables customer storm protection. Routers count locally and propagate temporary blocks lazily; distributed bursts can exceed this number. Not an HTTP request, byte or spending cap."
          },
          "name": {
            "type": "string",
            "maxLength": 120,
            "description": "Optional editable display name. Trimmed, allows duplicates, and may be cleared with an empty string. Control characters are not allowed. Does not change routing, URL or agent configuration."
          }
        }
      },
      "ErrorText": {
        "type": "string"
      },
      "AgentConfigSSH": {
        "type": "object",
        "description": "SSH backend settings. Auth fields are optional \u2014 omit all of them and the agent prompts the visitor in the browser terminal instead.",
        "properties": {
          "protocol": {
            "type": "string",
            "enum": [
              "ssh",
              "telnet"
            ],
            "description": "Default ssh. telnet ignores every auth field below."
          },
          "username": {
            "type": "string"
          },
          "private_key_path": {
            "type": "string",
            "description": "Absolute path (or ~/...) on the machine running the agent."
          },
          "passphrase_env": {
            "type": "string",
            "description": "Name of an env var on the agent host holding the key passphrase."
          },
          "password": {
            "type": "string",
            "description": "Stored encrypted server-side. Reads return the redaction marker __femtoport_redacted__; send that value back unchanged to keep the stored password."
          },
          "password_env": {
            "type": "string"
          },
          "known_hosts_path": {
            "type": "string"
          },
          "insecure_ignore_host_key_dangerous": {
            "type": "boolean"
          }
        }
      },
      "AgentConfigBasicAuthUser": {
        "type": "object",
        "required": [
          "username",
          "password_hash"
        ],
        "properties": {
          "username": {
            "type": "string"
          },
          "password_hash": {
            "type": "string",
            "description": "bcrypt hash. This is the only accepted shape \u2014 send a hash, not a plaintext password."
          }
        }
      },
      "AgentConfig": {
        "type": "object",
        "description": "The complete legal shape of a tunnel's agent_config. The server rejects unknown fields (json.Decoder.DisallowUnknownFields), so this schema IS the contract, not a hint.",
        "properties": {
          "schema": {
            "type": "integer",
            "description": "Blob-shape version, stamped by the server on every write. Omit on create."
          },
          "service": {
            "type": "string",
            "enum": [
              "http_proxy",
              "static_site",
              "ssh",
              "files",
              "vnc"
            ],
            "description": "Must match backend_mode when set: http_proxy<->proxy, static_site<->static, ssh<->ssh, files<->files, vnc<->vnc (Remote Desktop)."
          },
          "public_access_acknowledged": {
            "type": "boolean",
            "description": "Remote Desktop (vnc) only; rejected for every other backend. Explicitly accepts serving the desktop without a Basic auth user, so anyone with the URL can view and control it. Without this flag or an active Basic auth user in the tunnel access policy, the agent keeps the desktop unavailable. Send it on every create/update that should stay unprotected: an update without it clears it. Agents up to v2.5.63 ignore it and keep refusing."
          },
          "auth": {
            "type": "object",
            "properties": {
              "basic": {
                "type": "object",
                "required": [
                  "users"
                ],
                "properties": {
                  "realm": {
                    "type": "string"
                  },
                  "users": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/AgentConfigBasicAuthUser"
                    },
                    "minItems": 1,
                    "maxItems": 32
                  }
                }
              }
            }
          },
          "ssh": {
            "$ref": "#/components/schemas/AgentConfigSSH"
          }
        }
      },
      "TunnelListResponse": {
        "type": "object",
        "required": [
          "tunnels"
        ],
        "properties": {
          "tunnels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tunnel"
            }
          }
        }
      },
      "TunnelCreateRequest": {
        "type": "object",
        "required": [
          "target"
        ],
        "properties": {
          "target": {
            "type": "string",
            "description": "Local target: http(s) URL for proxy, absolute folder path for static or files, host:port for ssh. Remote Desktop (vnc) uses desktop for built-in local hosting, or an external server's host:port. Files requires tunnel Basic auth with a user. Remote Desktop strongly recommends it; without a user it needs agent_config.public_access_acknowledged true, otherwise the agent keeps it unavailable."
          },
          "backend_mode": {
            "type": "string",
            "enum": [
              "proxy",
              "static",
              "ssh",
              "files",
              "vnc"
            ],
            "default": "proxy"
          },
          "tls_mode": {
            "type": "string",
            "description": "Compatibility only. When sent it must be 'terminated' (the only value the create/update path accepts); end-to-end TLS is set exclusively via POST /api/v1/tunnels/{id}/e2e."
          },
          "cert_source": {
            "type": "string",
            "description": "Compatibility only. When sent it must be 'shared_wildcard'."
          },
          "token_label": {
            "type": "string",
            "description": "Label for the first agent token minted with the tunnel. Defaults to \"initial\"."
          },
          "agent_config": {
            "$ref": "#/components/schemas/AgentConfig"
          },
          "name": {
            "type": "string",
            "maxLength": 120,
            "description": "Optional editable display name. Trimmed, allows duplicates, and may be cleared with an empty string. Control characters are not allowed. Does not change routing, URL or agent configuration."
          }
        }
      },
      "TunnelUpdateRequest": {
        "type": "object",
        "properties": {
          "target": {
            "type": "string",
            "description": "Local backend target. Remote Desktop (vnc) uses desktop for built-in local hosting, or an external server's host:port."
          },
          "backend_mode": {
            "type": "string",
            "enum": [
              "proxy",
              "static",
              "ssh",
              "files",
              "vnc"
            ],
            "default": "proxy"
          },
          "tls_mode": {
            "type": "string",
            "description": "Compatibility only; must be 'terminated' when sent."
          },
          "cert_source": {
            "type": "string",
            "description": "Compatibility only; must be 'shared_wildcard' when sent."
          },
          "agent_config": {
            "$ref": "#/components/schemas/AgentConfig"
          },
          "name": {
            "type": "string",
            "maxLength": 120,
            "description": "Optional editable display name. Trimmed, allows duplicates, and may be cleared with an empty string. Control characters are not allowed. Does not change routing, URL or agent configuration."
          }
        },
        "anyOf": [
          {
            "required": [
              "target"
            ]
          },
          {
            "required": [
              "name"
            ],
            "description": "Metadata-only update: send only name to rename without reapplying connection or access settings.",
            "not": {
              "anyOf": [
                {
                  "required": [
                    "target"
                  ]
                },
                {
                  "required": [
                    "backend_mode"
                  ]
                },
                {
                  "required": [
                    "tls_mode"
                  ]
                },
                {
                  "required": [
                    "cert_source"
                  ]
                },
                {
                  "required": [
                    "agent_config"
                  ]
                }
              ]
            }
          }
        ]
      },
      "TunnelCreateResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Tunnel"
          },
          {
            "type": "object",
            "required": [
              "token_id",
              "agent_token"
            ],
            "properties": {
              "token_id": {
                "type": "string"
              },
              "agent_token": {
                "type": "string",
                "description": "kpt_... bearer token, plaintext, shown once."
              }
            }
          }
        ]
      },
      "TunnelEnabledRequest": {
        "type": "object",
        "required": [
          "enabled"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "TunnelEnabledResponse": {
        "type": "object",
        "required": [
          "tunnel_id",
          "enabled"
        ],
        "properties": {
          "tunnel_id": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "TunnelE2ERequest": {
        "type": "object",
        "required": [
          "enabled"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "TunnelE2EResponse": {
        "type": "object",
        "required": [
          "tunnel_id",
          "e2e_enabled",
          "tls_mode",
          "cert_source"
        ],
        "properties": {
          "tunnel_id": {
            "type": "string"
          },
          "e2e_enabled": {
            "type": "boolean"
          },
          "tls_mode": {
            "enum": [
              "terminated",
              "passthrough"
            ]
          },
          "cert_source": {
            "type": "string"
          }
        }
      },
      "CustomDomainE2ERequest": {
        "type": "object",
        "required": [
          "enabled"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "TunnelToken": {
        "type": "object",
        "required": [
          "token_id",
          "tunnel_id",
          "label",
          "status",
          "created_at",
          "has_stored_secret"
        ],
        "properties": {
          "token_id": {
            "type": "string"
          },
          "tunnel_id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "revoked"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": "string",
            "format": "date-time"
          },
          "revoked_at": {
            "type": "string",
            "format": "date-time"
          },
          "has_stored_secret": {
            "type": "boolean",
            "description": "Whether the plaintext is stored for later reveal (tokens issued before token re-display shipped have no stored secret)."
          }
        }
      },
      "TunnelTokenListResponse": {
        "type": "object",
        "required": [
          "tokens"
        ],
        "properties": {
          "tokens": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TunnelToken"
            }
          }
        }
      },
      "TunnelTokenIssueRequest": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Defaults to issued-<UTC timestamp>."
          }
        }
      },
      "TunnelTokenIssueResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TunnelToken"
          },
          {
            "type": "object",
            "required": [
              "agent_token"
            ],
            "properties": {
              "agent_token": {
                "type": "string",
                "description": "kpt_... plaintext, shown once."
              }
            }
          }
        ]
      },
      "TokenRevealRequestResponse": {
        "type": "object",
        "required": [
          "status",
          "challenge_id"
        ],
        "properties": {
          "status": {
            "type": "string"
          },
          "challenge_id": {
            "type": "string"
          }
        }
      },
      "TokenRevealVerifyRequest": {
        "type": "object",
        "required": [
          "challenge_id",
          "code"
        ],
        "properties": {
          "challenge_id": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "pattern": "^[0-9]{8}$"
          }
        }
      },
      "TokenRevealVerifyResponse": {
        "type": "object",
        "required": [
          "agent_token",
          "sni",
          "label"
        ],
        "properties": {
          "agent_token": {
            "type": "string"
          },
          "sni": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        }
      },
      "TunnelAccessUser": {
        "type": "object",
        "required": [
          "access_user_id",
          "username",
          "mfa_enabled",
          "mfa_configured",
          "status",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "access_user_id": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "mfa_enabled": {
            "type": "boolean"
          },
          "mfa_configured": {
            "type": "boolean",
            "description": "Whether a TOTP secret is actually stored \u2014 must be true before mfa_enabled can be turned on for this user."
          },
          "status": {
            "enum": [
              "active",
              "disabled"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TunnelAccessPolicy": {
        "type": "object",
        "required": [
          "basic_enabled",
          "mfa_enabled",
          "realm",
          "session_ttl_seconds",
          "auth_epoch",
          "users"
        ],
        "properties": {
          "basic_enabled": {
            "type": "boolean"
          },
          "mfa_enabled": {
            "type": "boolean",
            "description": "Requires basic_enabled and every active access user to already have MFA configured."
          },
          "realm": {
            "type": "string"
          },
          "session_ttl_seconds": {
            "type": "integer"
          },
          "auth_epoch": {
            "type": "integer",
            "format": "int64",
            "description": "Bumped on every policy or user change; edged uses it to invalidate cached access-gate sessions."
          },
          "users": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TunnelAccessUser"
            }
          },
          "user_result": {
            "type": "object",
            "description": "Present after POST only; describes this committed user mutation. Saving does not confirm remote agent application.",
            "required": [
              "access_user_id",
              "outcome"
            ],
            "properties": {
              "access_user_id": {
                "type": "string"
              },
              "outcome": {
                "type": "string",
                "enum": [
                  "created",
                  "updated"
                ]
              }
            }
          }
        }
      },
      "TunnelAccessPolicyUpdateRequest": {
        "type": "object",
        "required": [
          "session_ttl_seconds"
        ],
        "properties": {
          "basic_enabled": {
            "type": "boolean"
          },
          "mfa_enabled": {
            "type": "boolean",
            "description": "400 if true while any active access user lacks a configured TOTP secret."
          },
          "realm": {
            "type": "string",
            "description": "Defaults to \"Femtoport\" when empty."
          },
          "session_ttl_seconds": {
            "type": "integer",
            "minimum": 300,
            "maximum": 1209600,
            "description": "Required; between 300 (5m) and 1209600 (14d)."
          }
        }
      },
      "TunnelAccessUserCreateRequest": {
        "type": "object",
        "required": [
          "username",
          "password"
        ],
        "properties": {
          "username": {
            "type": "string",
            "maxLength": 128,
            "description": "Case-insensitive key within this tunnel. Existing active or removed users are updated and activated; their ID is preserved."
          },
          "password": {
            "type": "string",
            "maxLength": 1024,
            "description": "Required; replaces the existing password and is hashed with bcrypt server-side."
          },
          "mfa_enabled": {
            "type": "boolean",
            "description": "Omit to preserve existing user MFA (new users default to false). Explicit false disables user MFA unless tunnel-wide MFA requires it. Enabled MFA requires a configured TOTP secret."
          },
          "totp_secret_b32": {
            "type": "string",
            "description": "Omit to preserve the existing secret, including for a removed user. A nonempty value replaces it. Empty clears it only if resulting user MFA and tunnel-wide MFA are disabled."
          }
        }
      },
      "TunnelAccessUserPatchRequest": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "maxLength": 128
          },
          "password": {
            "type": "string",
            "maxLength": 1024
          },
          "mfa_enabled": {
            "type": "boolean"
          },
          "totp_secret_b32": {
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "disabled"
            ]
          }
        }
      },
      "ConnectedAgent": {
        "type": "object",
        "required": [
          "instance_id",
          "host_label",
          "os",
          "arch",
          "version",
          "sessions",
          "routers",
          "active_ssh_sessions",
          "last_seen"
        ],
        "properties": {
          "instance_id": {
            "type": "string"
          },
          "host_label": {
            "type": "string"
          },
          "os": {
            "type": "string"
          },
          "arch": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "sessions": {
            "type": "integer",
            "description": "Live session count for this agent instance (usually one per router)."
          },
          "routers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "active_ssh_sessions": {
            "type": "integer",
            "description": "Attached browser console or remote desktop sessions currently delaying an agent update. The field name is retained for wire compatibility."
          },
          "last_seen": {
            "type": "string",
            "format": "date-time"
          },
          "update_state": {
            "type": "string",
            "description": "Self-update health as last reported by the agent (v2.5.25+); empty for older agents."
          },
          "pending_version": {
            "type": "string"
          },
          "last_update_error": {
            "type": "string"
          },
          "control_socket_state": {
            "type": "string",
            "enum": [
              "ok",
              "retrying",
              "unavailable",
              "disabled"
            ],
            "description": "State of the local agent control socket."
          },
          "control_socket_error": {
            "type": "string",
            "maxLength": 200
          },
          "control_socket_changed_at": {
            "type": "string",
            "format": "date-time"
          },
          "backend_settings": {
            "type": "object",
            "description": "Per-session reports for the current saved backend and access settings. Counts exclude draining connections.",
            "required": ["applied", "pending", "rejected", "local_disabled", "unsupported", "unavailable"],
            "properties": {
              "applied": {"type": "integer", "minimum": 0},
              "pending": {"type": "integer", "minimum": 0},
              "rejected": {"type": "integer", "minimum": 0},
              "local_disabled": {"type": "integer", "minimum": 0},
              "unsupported": {"type": "integer", "minimum": 0},
              "unavailable": {"type": "integer", "minimum": 0}
            }
          }
        }
      },
      "ConnectedAgentsResponse": {
        "type": "object",
        "required": [
          "agents"
        ],
        "properties": {
          "agents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConnectedAgent"
            }
          }
        }
      },
      "WorkspaceRef": {
        "type": "object",
        "required": [
          "workspace_id",
          "workspace_name"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "workspace_name": {
            "type": "string"
          }
        }
      },
      "Me": {
        "type": "object",
        "required": [
          "user_id",
          "email",
          "token_id",
          "token_kind",
          "role",
          "workspace_id",
          "workspace_name",
          "workspace_status",
          "balance_bytes",
          "granted_bytes",
          "used_bytes",
          "latest_grant_bytes",
          "used_since_latest_grant_bytes",
          "free_trial_claimed",
          "billing_configured",
          "turnstile_configured",
          "legal_acceptance_required",
          "usage_basis",
          "reserved_bytes",
          "available_credit_bytes",
          "account_access",
          "tunnel_capacity"
        ],
        "properties": {
          "user_id": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "token_id": {
            "type": "string",
            "description": "The token authenticating this request."
          },
          "token_kind": {
            "enum": [
              "session",
              "machine"
            ]
          },
          "role": {
            "enum": [
              "owner",
              "admin",
              "member",
              "viewer"
            ]
          },
          "workspace_id": {
            "type": "string"
          },
          "workspace_name": {
            "type": "string"
          },
          "workspace_status": {
            "type": "string"
          },
          "balance_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "granted_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "used_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "entitled_until": {
            "type": "string",
            "format": "date-time"
          },
          "latest_grant_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "latest_grant_created_at": {
            "type": "string",
            "format": "date-time"
          },
          "used_since_latest_grant_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "other_workspaces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WorkspaceRef"
            },
            "description": "The caller's other accessible workspaces, excluding the current one. Omitted when there is only one. Capped at 10."
          },
          "free_trial_claimed": {
            "type": "boolean"
          },
          "billing_configured": {
            "type": "boolean",
            "description": "When false, /api/v1/billing/products and /checkouts return 503."
          },
          "turnstile_configured": {
            "type": "boolean"
          },
          "turnstile_site_key": {
            "type": "string"
          },
          "platform_admin": {
            "type": "boolean",
            "description": "True only for code-configured platform admins on a session token."
          },
          "legal_acceptance_required": {
            "type": "boolean"
          },
          "usage_basis": {
            "type": "string",
            "description": "Plain-language explanation of the selected traffic billing basis."
          },
          "service_capacity_limited": {
            "type": "boolean",
            "description": "Service capacity is temporarily limited for this workspace. Account navigation and recorded balances remain available; additional customer credit does not resolve this state."
          },
          "accounting_recovery_required": {
            "type": "boolean",
            "description": "Service requires operator recovery. Account navigation and recorded balances remain readable; additional credit does not clear this condition."
          },
          "credit_adjustment_pending": {
            "type": "boolean",
            "description": "Internal credit adjustment is pending. Connections may pause; adding credit does not clear this hold. Independent of service capacity and credit exhaustion."
          },
          "refund_payment_returned": {
            "type": "boolean",
            "description": "A confirmed provider refund has a still-pending internal credit adjustment. The payment is already returned; no second refund request is needed."
          },
          "reserved_bytes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "minimum": 0,
            "description": "Issued stream traffic allowance not yet proved, returned unused or disposed. Includes idle reservations and traffic awaiting confirmation, possibly allowed overdraft; it is not confirmed usage. Null when this accounting basis is unavailable. Independent service holds still apply."
          },
          "available_credit_bytes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "minimum": 0,
            "description": "Nonnegative paid credit balance not reserved by current stream traffic rights. Excludes the allowed overdraft and does not authorize traffic while a separate service hold or entitlement restriction applies. Null when reservation state is unavailable."
          },
          "latest_usage_confirmation_at": {
            "type": "string",
            "format": "date-time",
            "description": "Database timestamp of the most recent recorded positive stream proof. Not a completeness watermark for all connections. Absent when no retained positive proof record exists."
          },
          "refund_cases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RefundCase"
            }
          },
          "refund_cases_more": {
            "type": "boolean"
          },
          "account_access": {
            "type": "boolean",
            "description": "True for email-verified account sign-in, including verified registration. Workspace API keys and sessions obtained from them cannot manage account-wide identity, security, sessions, invitations, referrals or the billing portal."
          },
          "tunnel_capacity": {
            "$ref": "#/components/schemas/TunnelCapacity"
          }
        }
      },
      "Workspace": {
        "type": "object",
        "required": [
          "workspace_id",
          "workspace_name",
          "role",
          "current"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "workspace_name": {
            "type": "string"
          },
          "role": {
            "enum": [
              "owner",
              "admin",
              "member",
              "viewer"
            ]
          },
          "current": {
            "type": "boolean"
          }
        }
      },
      "WorkspaceListResponse": {
        "type": "object",
        "required": [
          "workspaces"
        ],
        "properties": {
          "workspaces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Workspace"
            }
          }
        }
      },
      "WorkspaceCreateRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80,
            "description": "Defaults to \"Unnamed\" when empty."
          },
          "request_id": {
            "type": "string",
            "minLength": 16,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]{16,128}$",
            "description": "Generate once per intended creation. Reuse with the same name after a timeout or 503, including across sessions or gateway replicas. Scoped to the current user."
          }
        },
        "required": [
          "request_id"
        ]
      },
      "WorkspaceUpdateRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80,
            "description": "Defaults to \"Unnamed\" when empty."
          }
        }
      },
      "WorkspaceSwitchRequest": {
        "type": "object",
        "required": [
          "workspace_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          }
        }
      },
      "Session": {
        "type": "object",
        "required": [
          "token_id",
          "workspace_id",
          "kind",
          "label",
          "role",
          "created_at",
          "is_current"
        ],
        "properties": {
          "token_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "session",
              "machine"
            ]
          },
          "label": {
            "type": "string"
          },
          "role": {
            "enum": [
              "owner",
              "admin",
              "member",
              "viewer"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Absent for non-expiring machine tokens."
          },
          "is_current": {
            "type": "boolean"
          }
        }
      },
      "SessionListResponse": {
        "type": "object",
        "required": [
          "sessions"
        ],
        "properties": {
          "sessions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Session"
            }
          }
        }
      },
      "LegalDoc": {
        "type": "object",
        "required": [
          "release_date",
          "document_sha256"
        ],
        "properties": {
          "release_date": {
            "type": "string",
            "format": "date"
          },
          "document_sha256": {
            "type": "string"
          },
          "user_accepted_release_date": {
            "type": "string",
            "format": "date"
          },
          "user_accepted_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LegalCurrent": {
        "type": "object",
        "required": [
          "tos",
          "privacy",
          "acceptance_required"
        ],
        "properties": {
          "tos": {
            "$ref": "#/components/schemas/LegalDoc"
          },
          "privacy": {
            "$ref": "#/components/schemas/LegalDoc"
          },
          "acceptance_required": {
            "type": "boolean"
          }
        }
      },
      "AuditEvent": {
        "type": "object",
        "required": [
          "log_id",
          "at",
          "action",
          "detail"
        ],
        "properties": {
          "log_id": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "actor_user_id": {
            "type": "string"
          },
          "actor_token_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "detail": {
            "type": "object",
            "additionalProperties": true
          },
          "source_ip": {
            "type": "string"
          }
        }
      },
      "AuditListResponse": {
        "type": "object",
        "required": [
          "events"
        ],
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            }
          },
          "next_cursor": {
            "type": "string",
            "description": "Opaque \"<at_unix_micro>:<log_id>\" cursor; pass back as ?cursor= for the next page. Absent on the last page."
          }
        }
      },
      "InviteRedemption": {
        "type": "object",
        "required": [
          "email",
          "redeemed_at"
        ],
        "properties": {
          "email": {
            "type": "string"
          },
          "redeemed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Invite": {
        "type": "object",
        "required": [
          "code_id",
          "code",
          "share_url",
          "status",
          "max_uses",
          "used_count",
          "created_at",
          "redemptions"
        ],
        "properties": {
          "code_id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "share_url": {
            "type": "string",
            "format": "uri",
            "description": "Absolute link pre-filled with the code; hand this to the invitee."
          },
          "status": {
            "enum": [
              "active",
              "pending",
              "expired",
              "used_up",
              "revoked"
            ]
          },
          "bound_email": {
            "type": "string",
            "format": "email"
          },
          "note": {
            "type": "string"
          },
          "max_uses": {
            "type": "integer"
          },
          "used_count": {
            "type": "integer"
          },
          "valid_until": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "redemptions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InviteRedemption"
            }
          }
        }
      },
      "InvitesListResponse": {
        "type": "object",
        "required": [
          "invites",
          "quota",
          "used_slots",
          "enabled"
        ],
        "properties": {
          "invites": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Invite"
            }
          },
          "quota": {
            "type": "integer",
            "description": "Caller's pending-invite limit."
          },
          "used_slots": {
            "type": "integer",
            "description": "Caller's outstanding (not revoked, not fully used) invite count."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the operator has the user-invite surface turned on."
          }
        }
      },
      "InviteCreateRequest": {
        "type": "object",
        "properties": {
          "bound_email": {
            "type": "string",
            "format": "email",
            "description": "Optional; locks the invite to one address."
          },
          "expires_in_days": {
            "type": "integer",
            "description": "Optional, capped at 365. 0/absent means no expiry."
          },
          "note": {
            "type": "string",
            "maxLength": 500
          }
        }
      },
      "ProductView": {
        "type": "object",
        "required": [
          "product_id",
          "name",
          "price_amount_cents",
          "price_currency",
          "credit_bytes",
          "entitlement_days"
        ],
        "properties": {
          "product_id": {
            "type": "string",
            "description": "Provider product id; the value POST /billing/checkouts expects as product_id."
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "price_amount_cents": {
            "type": "integer",
            "format": "int64"
          },
          "price_currency": {
            "type": "string"
          },
          "recurring_interval": {
            "type": "string",
            "description": "Empty for one-time top-ups; present for subscription tiers."
          },
          "credit_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "entitlement_days": {
            "type": "integer",
            "format": "int64"
          },
          "grants_feature": {
            "type": "string",
            "description": "Workspace capability this purchase unlocks (e.g. e2e_tls). Absent for plain credit top-ups."
          },
          "feature_granted": {
            "type": "boolean",
            "description": "True when the active workspace already holds grants_feature."
          },
          "tunnel_limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "Total tunnel allowance granted to this workspace. The highest active grant wins; allowances do not add."
          },
          "tunnel_capacity_granted": {
            "type": "boolean",
            "description": "The workspace already has at least this total allowance. Does not prevent purchasing traffic or service time."
          }
        }
      },
      "ProductsListResponse": {
        "type": "object",
        "required": [
          "one_time",
          "subscriptions"
        ],
        "properties": {
          "one_time": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductView"
            }
          },
          "subscriptions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductView"
            }
          }
        }
      },
      "CreateCheckoutRequest": {
        "type": "object",
        "required": [
          "product_id",
          "operation_id"
        ],
        "properties": {
          "product_id": {
            "type": "string"
          },
          "operation_id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_-]{8,96}$",
            "description": "Stable client-generated identifier. Reuse it after any interrupted or pending create response."
          }
        }
      },
      "CreateCheckoutResponse": {
        "type": "object",
        "required": [
          "operation_id",
          "intent_id",
          "status"
        ],
        "properties": {
          "checkout_id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "HTTPS hosted URL, present only after durable provider binding. Do not redirect a pending response."
          },
          "operation_id": {
            "type": "string"
          },
          "intent_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "pending"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "VerifyCheckoutRequest": {
        "type": "object",
        "required": [
          "checkout_id"
        ],
        "properties": {
          "checkout_id": {
            "type": "string"
          }
        }
      },
      "VerifyCheckoutResponse": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "enum": [
              "pending",
              "processing",
              "credited"
            ]
          },
          "delta_bytes": {
            "type": "integer",
            "format": "int64",
            "description": "Credit granted by this exact paid order; present only when status is credited."
          }
        }
      },
      "FreeTrialActivateRequest": {
        "type": "object",
        "required": [
          "turnstile_token"
        ],
        "properties": {
          "turnstile_token": {
            "type": "string"
          }
        }
      },
      "FreeTrialActivateResponse": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string"
          },
          "granted_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "new_entitled_until": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RedeemCodeRequest": {
        "type": "object",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string"
          }
        }
      },
      "RedeemCodeResponse": {
        "type": "object",
        "required": [
          "applied"
        ],
        "properties": {
          "applied": {
            "type": "object",
            "properties": {
              "credit_bytes": {
                "type": "integer",
                "format": "int64"
              },
              "features": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "entitlement_seconds": {
                "type": "integer"
              },
              "tunnel_limit": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "Total tunnel allowance granted to this workspace. The highest active grant wins; allowances do not add."
              }
            }
          },
          "new_balance_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "effective_tunnel_limit": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000
          }
        }
      },
      "AccountMFAFactor": {
        "type": "object",
        "required": [
          "factor_id",
          "factor_type",
          "label",
          "status",
          "created_at"
        ],
        "properties": {
          "factor_id": {
            "type": "string"
          },
          "factor_type": {
            "type": "string",
            "const": "totp"
          },
          "label": {
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "active",
              "disabled"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "confirmed_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AccountMFAStatus": {
        "type": "object",
        "required": [
          "enabled",
          "factors",
          "recovery_codes_remaining"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "factors": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/AccountMFAFactor"
            }
          },
          "recovery_codes_remaining": {
            "type": "integer"
          }
        }
      },
      "AccountMFAEmailRequestResponse": {
        "type": "object",
        "required": [
          "challenge_id"
        ],
        "properties": {
          "challenge_id": {
            "type": "string"
          }
        }
      },
      "AccountMFAEmailVerifyRequest": {
        "type": "object",
        "required": [
          "challenge_id",
          "code"
        ],
        "properties": {
          "challenge_id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        }
      },
      "AccountMFAEmailVerifyResponse": {
        "type": "object",
        "required": [
          "enroll_challenge_id"
        ],
        "properties": {
          "enroll_challenge_id": {
            "type": "string",
            "description": "Short-lived ticket consumed by POST /account/mfa/totp/start."
          }
        }
      },
      "AccountMFATOTPStartRequest": {
        "type": "object",
        "required": [
          "enroll_challenge_id"
        ],
        "properties": {
          "enroll_challenge_id": {
            "type": "string"
          }
        }
      },
      "AccountMFATOTPStartResponse": {
        "type": "object",
        "required": [
          "factor_id",
          "secret",
          "otpauth_uri"
        ],
        "properties": {
          "factor_id": {
            "type": "string"
          },
          "secret": {
            "type": "string",
            "description": "Base32 TOTP secret."
          },
          "otpauth_uri": {
            "type": "string",
            "description": "otpauth://totp/... URI for QR display (see POST /qr/svg)."
          }
        }
      },
      "AccountMFATOTPConfirmRequest": {
        "type": "object",
        "required": [
          "factor_id",
          "code"
        ],
        "properties": {
          "factor_id": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "6-digit TOTP code."
          }
        }
      },
      "AccountMFATOTPConfirmResponse": {
        "type": "object",
        "required": [
          "factor",
          "recovery_codes"
        ],
        "properties": {
          "factor": {
            "$ref": "#/components/schemas/AccountMFAFactor"
          },
          "recovery_codes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "One-time recovery codes, shown once."
          }
        }
      },
      "AccountMFARecoveryCodesResponse": {
        "type": "object",
        "required": [
          "recovery_codes"
        ],
        "properties": {
          "recovery_codes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "PlatformAdminEntry": {
        "type": "object",
        "required": [
          "user_id",
          "email",
          "is_root"
        ],
        "properties": {
          "user_id": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "is_root": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_by_email": {
            "type": "string"
          }
        }
      },
      "PlatformAdminListResponse": {
        "type": "object",
        "required": [
          "admins"
        ],
        "properties": {
          "admins": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlatformAdminEntry"
            }
          }
        }
      },
      "AdminUser": {
        "type": "object",
        "required": [
          "user_id",
          "email",
          "status",
          "created_at",
          "updated_at",
          "platform_admin_row",
          "root_admin",
          "workspace_count"
        ],
        "properties": {
          "user_id": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "registered_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time"
          },
          "platform_admin_row": {
            "type": "boolean",
            "description": "Always false \u2014 DB rows never grant admin authority; see root_admin instead."
          },
          "root_admin": {
            "type": "boolean"
          },
          "workspace_count": {
            "type": "integer"
          },
          "public_referral_code": {
            "type": "string",
            "description": "Public reusable referral identifier; not a credential."
          },
          "referred_by_user_id": {
            "type": "string",
            "description": "Optional immutable acquisition attribution, reviewable for manual credit grants."
          }
        }
      },
      "AdminUserListResponse": {
        "type": "object",
        "required": [
          "items",
          "limit",
          "offset",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminUser"
            }
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "AdminWorkspace": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "status",
          "created_at",
          "updated_at",
          "created_by_user_id",
          "owner_emails",
          "granted_bytes",
          "used_bytes",
          "balance_bytes",
          "tunnel_count"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_by_user_id": {
            "type": "string"
          },
          "owner_emails": {
            "type": "string",
            "description": "Comma-separated."
          },
          "granted_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "used_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "balance_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "entitled_until": {
            "type": "string",
            "format": "date-time"
          },
          "tunnel_count": {
            "type": "integer"
          }
        }
      },
      "AdminWorkspaceListResponse": {
        "type": "object",
        "required": [
          "items",
          "limit",
          "offset",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminWorkspace"
            }
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "AdminTunnel": {
        "type": "object",
        "required": [
          "tunnel_id",
          "workspace_id",
          "workspace_name",
          "sni",
          "tls_mode",
          "cert_source",
          "backend_mode",
          "target",
          "enabled",
          "created_by_user_id",
          "created_at",
          "updated_at",
          "authorization_state",
          "authorization_reason",
          "availability_state",
          "availability_reason",
          "bytes_in_total",
          "bytes_out_total"
        ],
        "properties": {
          "tunnel_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "workspace_name": {
            "type": "string"
          },
          "sni": {
            "type": "string"
          },
          "tls_mode": {
            "type": "string"
          },
          "cert_source": {
            "type": "string"
          },
          "backend_mode": {
            "type": "string",
            "enum": [
              "proxy",
              "static",
              "ssh",
              "files",
              "vnc"
            ]
          },
          "target": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "created_by_user_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "authorization_state": {
            "type": "string"
          },
          "authorization_reason": {
            "type": "string"
          },
          "availability_state": {
            "type": "string"
          },
          "availability_reason": {
            "type": "string"
          },
          "bytes_in_total": {
            "type": "integer",
            "format": "int64"
          },
          "bytes_out_total": {
            "type": "integer",
            "format": "int64"
          },
          "last_observed_at": {
            "type": "string",
            "format": "date-time"
          },
          "live_router_id": {
            "type": "string"
          },
          "agent_version": {
            "type": "string"
          },
          "agent_last_seen": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AdminTunnelListResponse": {
        "type": "object",
        "required": [
          "items",
          "limit",
          "offset",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminTunnel"
            }
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "AdminGrant": {
        "type": "object",
        "required": [
          "event_id",
          "workspace_id",
          "workspace_name",
          "kind",
          "delta_bytes",
          "source_ref",
          "idempotency_key",
          "created_by_email",
          "created_at"
        ],
        "properties": {
          "event_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "workspace_name": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "delta_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "new_entitled_until": {
            "type": "string",
            "format": "date-time"
          },
          "source_ref": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "created_by_user_id": {
            "type": "string"
          },
          "created_by_email": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AdminGrantListResponse": {
        "type": "object",
        "required": [
          "items",
          "limit",
          "offset",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminGrant"
            }
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "AdminTakedown": {
        "type": "object",
        "required": [
          "request_id",
          "received_at",
          "sni",
          "claimed_url",
          "reporter_email",
          "reason_text",
          "source_ip",
          "status",
          "workspace_id",
          "workspace_name"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "sni": {
            "type": "string"
          },
          "claimed_url": {
            "type": "string"
          },
          "reporter_email": {
            "type": "string"
          },
          "reporter_email_verified_at": {
            "type": "string",
            "format": "date-time"
          },
          "reason_text": {
            "type": "string"
          },
          "source_ip": {
            "type": "string"
          },
          "turnstile_verified": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "reviewed_at": {
            "type": "string",
            "format": "date-time"
          },
          "reviewed_by_user_id": {
            "type": "string"
          },
          "reviewed_by_email": {
            "type": "string"
          },
          "decision_notes": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "workspace_name": {
            "type": "string"
          }
        }
      },
      "AdminTakedownListResponse": {
        "type": "object",
        "required": [
          "items",
          "limit",
          "offset",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminTakedown"
            }
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "AdminCodeCapability": {
        "type": "object",
        "required": [
          "capability"
        ],
        "properties": {
          "capability": {
            "enum": [
              "register",
              "credit",
              "feature",
              "tunnel_capacity"
            ]
          },
          "credit_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "feature_name": {
            "type": "string"
          },
          "entitlement_seconds": {
            "type": "integer",
            "maximum": 316224000,
            "minimum": 0,
            "description": "Service time in seconds, added on redemption."
          },
          "tunnel_limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "Total tunnel allowance granted to this workspace. The highest active grant wins; allowances do not add."
          }
        }
      },
      "AdminCode": {
        "type": "object",
        "required": [
          "code_id",
          "code",
          "max_uses",
          "used_count",
          "created_at",
          "status",
          "capabilities"
        ],
        "properties": {
          "code_id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "bound_email": {
            "type": "string"
          },
          "created_by_user_id": {
            "type": "string"
          },
          "created_by_email": {
            "type": "string"
          },
          "max_uses": {
            "type": "integer"
          },
          "used_count": {
            "type": "integer"
          },
          "valid_from": {
            "type": "string",
            "format": "date-time"
          },
          "valid_until": {
            "type": "string",
            "format": "date-time"
          },
          "revoked_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "enum": [
              "active",
              "pending",
              "expired",
              "used_up",
              "revoked"
            ]
          },
          "capabilities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminCodeCapability"
            }
          }
        }
      },
      "AdminCodeListResponse": {
        "type": "object",
        "required": [
          "items",
          "limit",
          "offset",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminCode"
            }
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "AdminCodeCreateRequest": {
        "type": "object",
        "required": [
          "capabilities"
        ],
        "properties": {
          "capabilities": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "capability"
              ],
              "properties": {
                "capability": {
                  "enum": [
                    "register",
                    "credit",
                    "feature"
                  ]
                },
                "credit_bytes": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Required (> 0) for the credit capability."
                },
                "feature_name": {
                  "type": "string",
                  "description": "Required for the feature capability; only e2e_tls is known."
                },
                "entitlement_seconds": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 316224000,
                  "description": "Service time in seconds, added on redemption."
                }
              }
            }
          },
          "bound_email": {
            "type": "string",
            "format": "email"
          },
          "valid_from": {
            "type": "string",
            "description": "YYYY-MM-DD or RFC3339."
          },
          "valid_until": {
            "type": "string",
            "description": "YYYY-MM-DD or RFC3339; must be after valid_from."
          },
          "max_uses": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "default": 1
          },
          "label": {
            "type": "string",
            "maxLength": 120
          },
          "note": {
            "type": "string",
            "maxLength": 200
          }
        }
      },
      "AdminWaitlistEntry": {
        "type": "object",
        "required": [
          "waitlist_id",
          "email",
          "created_at"
        ],
        "properties": {
          "waitlist_id": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "signup_source": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "notified_at": {
            "type": "string",
            "format": "date-time"
          },
          "converted_user_id": {
            "type": "string"
          }
        }
      },
      "AdminWaitlistListResponse": {
        "type": "object",
        "required": [
          "items",
          "limit",
          "offset",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminWaitlistEntry"
            }
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "AdminGrantIssueRequest": {
        "type": "object",
        "required": [
          "reason"
        ],
        "properties": {
          "delta_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "entitlement_days": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3660
          },
          "reason": {
            "type": "string",
            "maxLength": 500
          }
        }
      },
      "AdminTokenMintRequest": {
        "type": "object",
        "required": [
          "user_id",
          "role",
          "reason"
        ],
        "properties": {
          "user_id": {
            "type": "string"
          },
          "role": {
            "enum": [
              "owner",
              "admin",
              "member",
              "viewer"
            ]
          },
          "label": {
            "type": "string",
            "maxLength": 80
          },
          "reason": {
            "type": "string",
            "maxLength": 500
          }
        }
      },
      "AdminTokenMintResponse": {
        "type": "object",
        "required": [
          "token_id",
          "workspace_id",
          "user_id",
          "role",
          "label",
          "created_at",
          "api_token"
        ],
        "properties": {
          "token_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "role": {
            "enum": [
              "owner",
              "admin",
              "member",
              "viewer"
            ]
          },
          "label": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "api_token": {
            "type": "string",
            "description": "Plaintext kpm_ token, shown once."
          }
        }
      },
      "AdminRProxyMigrateRequest": {
        "type": "object",
        "description": "Either rproxy_domain_id or base_domain selects the target pool domain.",
        "properties": {
          "rproxy_domain_id": {
            "type": "string"
          },
          "base_domain": {
            "type": "string"
          },
          "new_sni": {
            "type": "string",
            "description": "Optional explicit new SNI; auto-allocated when omitted."
          },
          "reason": {
            "type": "string"
          }
        }
      },
      "AdminRProxyMigrateResponse": {
        "type": "object",
        "required": [
          "tunnel_id",
          "workspace_id",
          "old_sni",
          "new_sni",
          "new_rproxy_domain_id",
          "new_rproxy_base_domain",
          "sni_label"
        ],
        "properties": {
          "tunnel_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "old_sni": {
            "type": "string"
          },
          "new_sni": {
            "type": "string"
          },
          "old_rproxy_domain_id": {
            "type": "string"
          },
          "new_rproxy_domain_id": {
            "type": "string"
          },
          "old_rproxy_base_domain": {
            "type": "string"
          },
          "new_rproxy_base_domain": {
            "type": "string"
          },
          "sni_label": {
            "type": "string"
          }
        }
      },
      "AdminReasonRequest": {
        "type": "object",
        "required": [
          "reason"
        ],
        "properties": {
          "reason": {
            "type": "string",
            "maxLength": 500
          }
        }
      },
      "AdminEventItem": {
        "type": "object",
        "required": [
          "log_id",
          "at",
          "type"
        ],
        "properties": {
          "log_id": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "type": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          },
          "source_app": {
            "type": "string"
          },
          "actor_type": {
            "type": "string"
          },
          "actor_user_id": {
            "type": "string"
          },
          "actor_token_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "result": {
            "type": "string"
          },
          "visibility": {
            "type": "string"
          },
          "contains_pii": {
            "type": "boolean"
          },
          "contains_secret": {
            "type": "boolean"
          },
          "detail": {
            "type": "object",
            "additionalProperties": true
          },
          "source_ip": {
            "type": "string"
          }
        }
      },
      "AdminEventsResponse": {
        "type": "object",
        "required": [
          "events"
        ],
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminEventItem"
            }
          },
          "next_cursor": {
            "type": "string"
          }
        }
      },
      "AdminLogEntry": {
        "type": "object",
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "msg": {
            "type": "string"
          },
          "container": {
            "type": "string"
          },
          "pod": {
            "type": "string"
          },
          "namespace": {
            "type": "string"
          },
          "node": {
            "type": "string"
          }
        }
      },
      "AdminLogsResponse": {
        "type": "object",
        "required": [
          "entries",
          "query"
        ],
        "properties": {
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminLogEntry"
            }
          },
          "query": {
            "type": "string"
          }
        }
      },
      "AdminLogContainersResponse": {
        "type": "object",
        "required": [
          "containers"
        ],
        "properties": {
          "containers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "AdminAlertRule": {
        "type": "object",
        "required": [
          "group",
          "name",
          "state",
          "query",
          "duration_seconds"
        ],
        "properties": {
          "group": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "state": {
            "enum": [
              "inactive",
              "pending",
              "firing"
            ]
          },
          "severity": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "duration_seconds": {
            "type": "number"
          },
          "summary": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "health": {
            "type": "string"
          },
          "last_error": {
            "type": "string"
          },
          "last_evaluation": {
            "type": "string",
            "format": "date-time"
          },
          "labels": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "AdminActiveAlert": {
        "type": "object",
        "required": [
          "name",
          "state"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          },
          "state": {
            "enum": [
              "active",
              "suppressed",
              "unprocessed"
            ]
          },
          "starts_at": {
            "type": "string",
            "format": "date-time"
          },
          "summary": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "labels": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "AdminAlertsResponse": {
        "type": "object",
        "required": [
          "rules",
          "active",
          "receivers",
          "vmalert_ok",
          "alertmanager_ok",
          "generated_at"
        ],
        "properties": {
          "rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminAlertRule"
            }
          },
          "active": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminActiveAlert"
            }
          },
          "receivers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "vmalert_ok": {
            "type": "boolean",
            "description": "False when vmalert could not be reached; rules stays whatever the last-good fetch produced (possibly empty)."
          },
          "alertmanager_ok": {
            "type": "boolean"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MetricPanelInfo": {
        "type": "object",
        "required": [
          "id",
          "title",
          "section",
          "unit"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "section": {
            "type": "string"
          },
          "unit": {
            "enum": [
              "percent",
              "bytes_per_sec",
              "ops_per_sec",
              "seconds",
              "count"
            ]
          },
          "description": {
            "type": "string"
          }
        }
      },
      "MetricPanelsResponse": {
        "type": "object",
        "required": [
          "sections",
          "windows"
        ],
        "properties": {
          "sections": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "title",
                "panels"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "panels": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MetricPanelInfo"
                  }
                }
              }
            }
          },
          "windows": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Valid ?window= values, e.g. 15m, 1h, 6h, 24h, 7d."
          }
        }
      },
      "MetricRangeResponse": {
        "type": "object",
        "required": [
          "panel",
          "title",
          "unit",
          "window",
          "series"
        ],
        "properties": {
          "panel": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "window": {
            "type": "string"
          },
          "series": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "points"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "points": {
                  "type": "array",
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "minItems": 2,
                    "maxItems": 2
                  },
                  "description": "[unix_seconds, value] pairs."
                }
              }
            }
          }
        }
      },
      "AccountExportLegalAcceptance": {
        "type": "object",
        "required": [
          "acceptance_id",
          "workspace_id",
          "tos_release_date",
          "tos_sha256",
          "privacy_release_date",
          "privacy_sha256",
          "endpoint_attestation_version",
          "acceptance_method",
          "accepted_at"
        ],
        "properties": {
          "acceptance_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "tos_release_date": {
            "type": "string",
            "format": "date"
          },
          "tos_sha256": {
            "type": "string"
          },
          "privacy_release_date": {
            "type": "string",
            "format": "date"
          },
          "privacy_sha256": {
            "type": "string"
          },
          "endpoint_attestation_version": {
            "type": "string"
          },
          "acceptance_method": {
            "type": "string"
          },
          "source_ip": {
            "type": "string"
          },
          "user_agent": {
            "type": "string"
          },
          "accepted_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AdminNodeStats": {
        "type": "object",
        "required": [
          "name",
          "role",
          "address",
          "status",
          "status_detail",
          "targets",
          "alerts",
          "alerts_known"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "up",
              "degraded",
              "service_down",
              "unreachable",
              "stale"
            ],
            "description": "Monitoring verdict from every scrape target carrying this host's node label; not a Kubernetes Node condition. service_down: the only fresh target is failing, so host state is unknown. unreachable: two or more fresh targets, all failing."
          },
          "status_detail": {
            "type": "string",
            "description": "One sentence naming the failing scrape job(s), or the targets that are up."
          },
          "targets": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "job",
                "instance",
                "state",
                "age_seconds"
              ],
              "properties": {
                "job": {
                  "type": "string"
                },
                "instance": {
                  "type": "string"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "up",
                    "down",
                    "stale"
                  ]
                },
                "age_seconds": {
                  "type": "number",
                  "description": "Seconds since the last scrape attempt, successful or not."
                }
              }
            }
          },
          "alerts": {
            "type": "array",
            "description": "vmalert alerts currently firing with this node label.",
            "items": {
              "type": "object",
              "required": [
                "name",
                "severity"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "severity": {
                  "type": "string"
                }
              }
            }
          },
          "alerts_known": {
            "type": "boolean",
            "description": "False when the always-firing Watchdog is absent, so an empty alerts list is not evidence of no alerts."
          },
          "latest": {
            "type": "object",
            "properties": {
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "cpu_count": {
                "type": "integer"
              },
              "load1": {
                "type": "number"
              },
              "load5": {
                "type": "number"
              },
              "load15": {
                "type": "number"
              },
              "procs_running": {
                "type": "integer"
              },
              "procs_blocked": {
                "type": "integer"
              },
              "mem_total_bytes": {
                "type": "integer",
                "format": "int64"
              },
              "mem_available_bytes": {
                "type": "integer",
                "format": "int64"
              },
              "mem_used_bytes": {
                "type": "integer",
                "format": "int64"
              },
              "fs_root_total_bytes": {
                "type": "integer",
                "format": "int64"
              },
              "fs_root_avail_bytes": {
                "type": "integer",
                "format": "int64"
              },
              "fs_root_used_bytes": {
                "type": "integer",
                "format": "int64"
              },
              "cpu_busy_pct": {
                "type": "number"
              },
              "disk_read_bps": {
                "type": "number"
              },
              "disk_write_bps": {
                "type": "number"
              },
              "net_rx_bps": {
                "type": "number"
              },
              "net_tx_bps": {
                "type": "number"
              },
              "edged_mux_sessions": {
                "type": "number"
              },
              "edged_mux_streams": {
                "type": "number"
              },
              "edged_reparent_claimed_total": {
                "type": "number"
              },
              "edged_peer_mux_fail_per_sec": {
                "type": "number"
              }
            },
            "required": [
              "at",
              "cpu_count",
              "load1",
              "load5",
              "load15",
              "procs_running",
              "procs_blocked",
              "mem_total_bytes",
              "mem_available_bytes",
              "mem_used_bytes",
              "fs_root_total_bytes",
              "fs_root_avail_bytes",
              "fs_root_used_bytes",
              "cpu_busy_pct",
              "disk_read_bps",
              "disk_write_bps",
              "net_rx_bps",
              "net_tx_bps",
              "edged_mux_sessions",
              "edged_mux_streams",
              "edged_reparent_claimed_total",
              "edged_peer_mux_fail_per_sec"
            ]
          }
        }
      },
      "AdminStats": {
        "type": "object",
        "required": [
          "generated_at"
        ],
        "description": "Full platform-admin telemetry snapshot; every top-level block is independently optional because each source degrades on its own (a dead metrics store must not blank the rest of the page).",
        "properties": {
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "mgmt": {
            "type": "object",
            "properties": {
              "users": {
                "type": "integer"
              },
              "active_workspaces": {
                "type": "integer"
              },
              "tunnels": {
                "type": "integer"
              },
              "live_tunnels": {
                "type": "integer"
              }
            },
            "required": [
              "users",
              "active_workspaces",
              "tunnels",
              "live_tunnels"
            ]
          },
          "routes": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "authorization_counts": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                }
              },
              "availability_counts": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                }
              }
            },
            "required": [
              "total",
              "authorization_counts",
              "availability_counts"
            ]
          },
          "sessions": {
            "type": "object",
            "properties": {
              "live": {
                "type": "integer"
              },
              "live_tunnels": {
                "type": "integer"
              }
            },
            "required": [
              "live",
              "live_tunnels"
            ]
          },
          "traffic_1h": {
            "type": "object",
            "properties": {
              "bytes_in": {
                "type": "integer",
                "format": "int64"
              },
              "bytes_out": {
                "type": "integer",
                "format": "int64"
              },
              "debit_rows": {
                "type": "integer"
              }
            },
            "required": [
              "bytes_in",
              "bytes_out",
              "debit_rows"
            ]
          },
          "top_workspaces": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "workspace_id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "granted_bytes": {
                  "type": "integer",
                  "format": "int64"
                },
                "used_bytes": {
                  "type": "integer",
                  "format": "int64"
                },
                "balance_bytes": {
                  "type": "integer",
                  "format": "int64"
                }
              },
              "required": [
                "workspace_id",
                "name",
                "granted_bytes",
                "used_bytes",
                "balance_bytes"
              ]
            }
          },
          "takedowns": {
            "type": "object",
            "properties": {
              "active": {
                "type": "integer"
              },
              "pending_review": {
                "type": "integer"
              },
              "pending_verification": {
                "type": "integer"
              },
              "actioned": {
                "type": "integer"
              },
              "dismissed": {
                "type": "integer"
              },
              "oldest_active_at": {
                "type": "string",
                "format": "date-time"
              },
              "oldest_pending_at": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "active",
              "pending_review"
            ]
          },
          "nodes_error": {
            "type": "string",
            "description": "Set when the node panel could not be built; an empty nodes list is then 'cannot answer', not 'no hosts'."
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AdminNodeStats"
            }
          },
          "runtime_audit": {
            "type": "object",
            "properties": {
              "targets": {
                "type": "integer"
              },
              "jobs": {
                "type": "integer"
              },
              "missing_scrape": {
                "type": "integer"
              },
              "stale_scrape": {
                "type": "integer"
              },
              "version_drift": {
                "type": "integer"
              },
              "expected_sha": {
                "type": "string"
              },
              "build_info_summary": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "app": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "sha": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "app",
                    "version",
                    "sha",
                    "count"
                  ]
                }
              }
            },
            "required": [
              "targets",
              "jobs",
              "missing_scrape",
              "stale_scrape",
              "version_drift"
            ]
          },
          "e2e_tls": {
            "type": "object",
            "description": "activations_7d = mgmt.tunnels_archive rows with archived_reason='e2e_enabled' in the trailing 7 days (survives a later disable). active_tunnels = live tls_mode='passthrough' tunnels. custom_domains_free = custom domains on cert_source='agent_managed_acme'.",
            "properties": {
              "activations_7d": {
                "type": "integer"
              },
              "active_tunnels": {
                "type": "integer"
              },
              "custom_domains_free": {
                "type": "integer"
              },
              "issuance_headroom_limit": {
                "type": "integer"
              },
              "pool_domains": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "domain_id": {
                      "type": "string"
                    },
                    "base_domain": {
                      "type": "string"
                    },
                    "used": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "domain_id",
                    "base_domain",
                    "used",
                    "limit"
                  ]
                }
              }
            },
            "required": [
              "activations_7d",
              "active_tunnels",
              "custom_domains_free",
              "issuance_headroom_limit",
              "pool_domains"
            ]
          }
        }
      },
      "FeedbackRequest": {
        "type": "object",
        "required": [
          "message",
          "share_account_info"
        ],
        "properties": {
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4000,
            "description": "Feedback message, trimmed; whitespace-only messages are rejected."
          },
          "share_account_info": {
            "type": "boolean",
            "const": true,
            "description": "Acknowledges sharing the message, registered email, user ID, current workspace ID, and role with Femtoport."
          }
        }
      },
      "ReferralsResponse": {
        "type": "object",
        "required": [
          "code",
          "link",
          "attributed_registrations"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable reusable public referral identifier; grants no capabilities."
          },
          "link": {
            "type": "string",
            "format": "uri"
          },
          "attributed_registrations": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "RefundCase": {
        "type": "object",
        "properties": {
          "case_id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "adjustment_state": {
            "type": "string",
            "enum": [
              "pending",
              "settled"
            ]
          },
          "pending_reason": {
            "type": "string",
            "enum": [
              "awaiting_bank_settlement",
              "awaiting_isolation",
              "isolation_unavailable"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "review_due_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "next_update_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "review_sequence": {
            "type": "integer",
            "format": "int64"
          },
          "settled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "case_id",
          "workspace_id",
          "adjustment_state",
          "pending_reason",
          "created_at",
          "review_due_at",
          "next_update_at",
          "review_sequence",
          "settled_at"
        ]
      },
      "RefundCaseReviewRequest": {
        "type": "object",
        "required": [
          "operation_id",
          "expected_sequence",
          "pending_reason",
          "next_update_at"
        ],
        "properties": {
          "operation_id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_-]{8,96}$"
          },
          "expected_sequence": {
            "type": "integer",
            "minimum": 0
          },
          "pending_reason": {
            "type": "string",
            "enum": [
              "awaiting_bank_settlement",
              "awaiting_isolation",
              "isolation_unavailable"
            ]
          },
          "next_update_at": {
            "type": "string",
            "format": "date-time",
            "description": "Future database time, no more than 24 hours away. A review does not settle credit."
          }
        }
      },
      "ClosingProviderObligations": {
        "type": "object",
        "description": "Counts scoped to frozen closure purchase roots. All pinned roots require provider resolution; known orders and confirmed cancellation alone are not financial finality. No contact, hosted links or raw payloads.",
        "required": [
          "checkout_intents",
          "unknown_checkout_outcomes",
          "pending_subscription_cancellations",
          "known_payment_orders",
          "review_required"
        ],
        "properties": {
          "checkout_intents": {
            "type": "integer",
            "minimum": 0
          },
          "unknown_checkout_outcomes": {
            "type": "integer",
            "minimum": 0
          },
          "pending_subscription_cancellations": {
            "type": "integer",
            "minimum": 0
          },
          "known_payment_orders": {
            "type": "integer",
            "minimum": 0
          },
          "review_required": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "TunnelCapacity": {
        "type": "object",
        "required": [
          "limit",
          "count"
        ],
        "properties": {
          "limit": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "description": "Highest active workspace allowance. Zero means no creation capacity, never unlimited."
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "description": "Existing tunnels, including disabled tunnels. Exceeding the allowance does not disable them."
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/workspace/limits": {
      "get": {
        "operationId": "get_workspace_limits",
        "summary": "Read workspace limits and warning status",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current limits or policy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Status unavailable"
          }
        }
      }
    },
    "/api/v1/admin/warning-policy": {
      "get": {
        "operationId": "get_admin_warning_policy",
        "summary": "Read or adjust global workspace warning thresholds",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current limits or policy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Status unavailable"
          }
        }
      },
      "put": {
        "operationId": "put_admin_warning_policy",
        "summary": "Read or adjust global workspace warning thresholds",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current limits or policy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Status unavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "low_balance_bytes",
                  "runway_days",
                  "urgent_runway_days",
                  "expiry_days",
                  "urgent_expiry_days"
                ],
                "properties": {
                  "low_balance_bytes": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "runway_days": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "urgent_runway_days": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "expiry_days": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "urgent_expiry_days": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/healthz": {
      "get": {
        "summary": "Liveness probe",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is up"
          }
        },
        "operationId": "get_healthz"
      }
    },
    "/api/public/turnstile-config": {
      "get": {
        "summary": "Get public Turnstile site key for anonymous forms",
        "security": [],
        "responses": {
          "200": {
            "description": "Site key or empty string"
          }
        },
        "operationId": "get_public_turnstile_config"
      }
    },
    "/api/public/page-event": {
      "post": {
        "summary": "Submit first-party UI telemetry (closed-set labels)",
        "security": [],
        "responses": {
          "204": {
            "description": "Recorded"
          },
          "400": {
            "description": "Unknown label or type"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "operationId": "create_public_page_event"
      }
    },
    "/api/public/takedown": {
      "post": {
        "summary": "Submit public takedown report",
        "description": "Requires a valid Cloudflare Turnstile token for action takedown_submit, bound to the management portal hostname, and approved by server-side Siteverify. Unchallenged or failed requests create no actionable report and send no email. Email verification follows, then an operator reviews the report; no automatic suspension.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url",
                  "reporter_email",
                  "reason_text",
                  "turnstile_token"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "reporter_email": {
                    "type": "string",
                    "format": "email"
                  },
                  "reason_text": {
                    "type": "string",
                    "maxLength": 4096
                  },
                  "turnstile_token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted. status is pending_email_verification (challenge_id is the target for verify-code) or, for a report already verified, its current status with no mail sent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending_email_verification",
                        "pending_review",
                        "active"
                      ]
                    },
                    "challenge_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "403": {
            "description": "Captcha rejected (invalid token, wrong action or hostname, failed or unknown challenge, or rejected assessment). Email abuse@femtoport.com instead."
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Captcha not configured"
          },
          "502": {
            "description": "Captcha check failed (Turnstile backend unreachable)"
          }
        },
        "operationId": "submit_takedown"
      }
    },
    "/api/public/takedown/verify-code": {
      "post": {
        "summary": "Verify a takedown report with the emailed code",
        "description": "Consumes the 6-digit code from the verification email. Single use, expires after 10 minutes, is invalidated after too many wrong attempts. Using the code retires the link from the same email and the other way round.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "challenge_id",
                  "code"
                ],
                "properties": {
                  "challenge_id": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified; the report waits for human review. already_verified is true when the link got there first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "already_verified": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing fields, or the code is wrong, expired, used or retired"
          },
          "429": {
            "description": "Too many failed verification attempts from this IP"
          }
        },
        "operationId": "verify_takedown_code"
      }
    },
    "/api/public/waitlist": {
      "post": {
        "summary": "Join the launch waitlist",
        "description": "Records an email asking to be notified when signup becomes available. Offered on the verified new-user invite-code step. Requires a Cloudflare Turnstile token for waitlist_join.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "turnstile_token"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "source": {
                    "type": "string",
                    "description": "Attribution slug carried from the ?src= query param, if present."
                  },
                  "turnstile_token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recorded (idempotent per email)"
          },
          "400": {
            "description": "Bad request"
          },
          "403": {
            "description": "Captcha rejected"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "operationId": "create_public_waitlist"
      }
    },
    "/api/auth/start": {
      "post": {
        "summary": "Start email magic-link/code sign-in",
        "description": "Requires Cloudflare Turnstile token for action auth_start. Successful accepted responses are intentionally opaque.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "turnstile_token"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "turnstile_token": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string",
                    "description": "Optional invitation from a share link, retained for the registration step after identity verification."
                  },
                  "kind": {
                    "enum": [
                      "combined",
                      "link",
                      "code"
                    ]
                  },
                  "referral_code": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "Optional public referral identifier. Unknown identifiers do not prevent open registration; explicit value overrides the intent."
                  },
                  "intent": {
                    "type": "string",
                    "description": "Base64url UTF-8 JSON v1 management intent. Optional referral_code on any action; kind register lands on registration only. Product action survives authentication."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted; email may be sent if checks pass. If the Turnstile token is missing, returns { status: \"captcha_required\", captcha_required: true } without sending email."
          },
          "400": {
            "description": "Bad request"
          },
          "403": {
            "description": "Captcha rejected or email authentication not allowed on this host. Account existence and registration admission are not disclosed before identity verification."
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Captcha not configured"
          },
          "502": {
            "description": "Captcha check failed (Turnstile backend unreachable)"
          }
        },
        "operationId": "create_auth_start"
      }
    },
    "/api/auth/config": {
      "get": {
        "summary": "Read public auth provider configuration",
        "security": [],
        "responses": {
          "200": {
            "description": "{ email_auth_configured: bool }"
          }
        },
        "operationId": "get_auth_config"
      }
    },
    "/api/auth/session": {
      "get": {
        "summary": "Check browser session state",
        "security": [],
        "responses": {
          "200": {
            "description": "{ authenticated: bool }"
          },
          "503": {
            "description": "Session status is temporarily unavailable. The session cookie is retained."
          }
        },
        "operationId": "get_auth_session"
      }
    },
    "/api/auth/verify-code": {
      "post": {
        "summary": "Complete email-code sign-in",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "challenge_id",
                  "code"
                ],
                "properties": {
                  "challenge_id": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created; cookie set"
          },
          "202": {
            "description": "Existing user: MFA required with mfa_challenge_id and methods. New identity: registration_required=true and an HttpOnly registration cookie; complete POST /api/auth/registration."
          },
          "401": {
            "description": "Bad or expired code"
          }
        },
        "operationId": "create_auth_verify_code"
      }
    },
    "/api/auth/verify-link": {
      "get": {
        "summary": "Show email-link sign-in confirmation",
        "description": "Displays the email address bound to the proof and a confirmation form. GET and HEAD do not consume the challenge or establish a session.",
        "security": [],
        "responses": {
          "200": {
            "description": "Email-bound confirmation page; no session is created.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "302": {
            "description": "Invalid or expired proof redirects to sign-in."
          }
        },
        "operationId": "get_auth_verify_link"
      },
      "post": {
        "summary": "Confirm email-link sign-in",
        "description": "Consumes the emailed proof once after explicit same-origin form submission, then continues through account registration or MFA as required.",
        "security": [],
        "responses": {
          "302": {
            "description": "Session created; redirects into the management UI"
          },
          "401": {
            "description": "Bad or expired link"
          },
          "400": {
            "description": "Invalid sign-in confirmation form."
          }
        },
        "operationId": "confirmEmailLinkSignIn",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "c",
                  "t"
                ],
                "properties": {
                  "c": {
                    "type": "string"
                  },
                  "t": {
                    "type": "string"
                  },
                  "intent": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/mfa/verify": {
      "post": {
        "summary": "Complete MFA challenge during sign-in",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "challenge_id",
                  "method"
                ],
                "properties": {
                  "challenge_id": {
                    "type": "string"
                  },
                  "method": {
                    "enum": [
                      "totp",
                      "recovery_code"
                    ]
                  },
                  "code": {
                    "type": "string",
                    "description": "6-digit TOTP code when method is totp"
                  },
                  "recovery_code": {
                    "type": "string",
                    "description": "Recovery code when method is recovery_code"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created; cookie set"
          },
          "400": {
            "description": "Bad or expired MFA challenge or invalid code."
          },
          "429": {
            "description": "Too many verification attempts."
          },
          "503": {
            "description": "Temporarily unavailable. Verification backend failures do not consume a bad-code attempt. Retry later.",
            "headers": {
              "Retry-After": {
                "description": "Seconds before retrying.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "create_auth_mfa_verify"
      }
    },
    "/api/auth/token-login": {
      "post": {
        "summary": "Exchange a machine API token for a browser session",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "Active kpm_ machine API token"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created; cookie set"
          },
          "401": {
            "description": "Invalid or revoked token"
          },
          "403": {
            "description": "Token is not a machine API token"
          },
          "429": {
            "description": "Too many failed sign-in attempts. Wait for the Retry-After interval."
          },
          "503": {
            "description": "Sign-in is temporarily unavailable. Retry with the same API key."
          }
        },
        "operationId": "create_auth_token_login"
      }
    },
    "/api/auth/logout": {
      "post": {
        "summary": "Revoke current session or bearer token",
        "responses": {
          "204": {
            "description": "Revoked or already signed out"
          },
          "503": {
            "description": "Revocation could not be confirmed. Retry with the same credential."
          }
        },
        "operationId": "create_auth_logout"
      }
    },
    "/api/v1/me": {
      "get": {
        "summary": "Get current account and workspace state",
        "responses": {
          "200": {
            "description": "Current account state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing token"
          },
          "503": {
            "description": "Service temporarily at capacity or unavailable. Retry later; additional customer credit does not resolve service capacity.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "service_capacity_unavailable for exhausted service capacity."
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "operationId": "get_me"
      }
    },
    "/api/v1/workspaces": {
      "get": {
        "summary": "List workspaces",
        "responses": {
          "200": {
            "description": "Workspace list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceListResponse"
                }
              }
            }
          }
        },
        "operationId": "list_workspaces"
      },
      "post": {
        "summary": "Create workspace",
        "responses": {
          "400": {
            "description": "Invalid request_id or workspace name exceeds 80 bytes."
          },
          "503": {
            "description": "Service temporarily at capacity or unavailable. Retry later; additional customer credit does not resolve service capacity.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "service_capacity_unavailable for exhausted service capacity."
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "201": {
            "description": "Created workspace and session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Workspace"
                }
              }
            }
          },
          "404": {
            "description": "The created workspace is no longer accessible."
          },
          "409": {
            "description": "Confirmed aborted creation (workspace_creation_aborted) or changed input for the same request_id (workspace_creation_request_conflict).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceCreateRequest"
              }
            }
          }
        },
        "operationId": "create_workspace",
        "description": "Creates at most one workspace per user and request_id. Retry identical input after an uncertain reply; success mints a fresh session only if the user still has access. A replay returns the current workspace name and role. A confirmed aborted request returns workspace_creation_aborted; use a new request_id to try creation again. Changed input returns workspace_creation_request_conflict. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient."
      }
    },
    "/api/v1/workspaces/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "summary": "Rename workspace",
        "responses": {
          "200": {
            "description": "Renamed workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Workspace"
                }
              }
            }
          },
          "400": {
            "description": "Workspace name exceeds 80 chars"
          },
          "403": {
            "description": "Rename requires owner or admin"
          },
          "404": {
            "description": "Workspace not found"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceUpdateRequest"
              }
            }
          }
        },
        "operationId": "update_workspaces"
      },
      "delete": {
        "summary": "Delete workspace",
        "description": "Owner-only terminal closure. First prepare and save a closing receipt kit, then send its reference/key and acknowledge recovery_saved. Current authority, cutoff attachment and normal-access revocation commit together. Closed workspaces cannot be reactivated. Credit and accounting obligations remain recorded. If the response is lost, use the saved receipt link to check the result before retrying.",
        "responses": {
          "204": {
            "description": "Workspace deleted"
          },
          "403": {
            "description": "Owner or admin access required"
          },
          "404": {
            "description": "Workspace or prepared receipt unavailable"
          },
          "400": {
            "description": "Save and acknowledge a valid kit first"
          },
          "503": {
            "description": "Accounting requires recovery or receipts unavailable"
          }
        },
        "operationId": "delete_workspaces",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "receipt_id",
                  "retrieval_key",
                  "recovery_saved"
                ],
                "properties": {
                  "receipt_id": {
                    "type": "string"
                  },
                  "retrieval_key": {
                    "type": "string"
                  },
                  "recovery_saved": {
                    "type": "boolean",
                    "const": true
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/workspaces/switch": {
      "post": {
        "summary": "Switch active browser workspace",
        "responses": {
          "200": {
            "description": "New browser session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Workspace"
                }
              }
            }
          },
          "400": {
            "description": "Missing workspace_id"
          },
          "404": {
            "description": "Workspace not found or caller has no access"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceSwitchRequest"
              }
            }
          }
        },
        "operationId": "switch_workspace",
        "description": "Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient."
      }
    },
    "/api/v1/tunnels": {
      "get": {
        "summary": "List tunnels",
        "description": "Lists tunnels in the active workspace. Each entry carries sni/public_url/tls_mode/cert_source/enabled/target/backend_mode plus agent session and traffic rollups. For LLM automation: after creating a tunnel, fetch this to confirm routing; see also https://femtoport.com/docs/run-the-agent-with-docker for Docker target networking (service DNS name, not localhost inside container).",
        "responses": {
          "200": {
            "description": "Tunnel list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelListResponse"
                }
              }
            }
          }
        },
        "operationId": "list_tunnels"
      },
      "post": {
        "summary": "Create tunnel",
        "description": "Creates a tunnel. Body { target, backend_mode=\"proxy\"|\"static\"|\"ssh\"|\"files\"|\"vnc\" }. Targets: proxy http://localhost:3000 or http://<lan-host>:<port>; static/files absolute directory /var/www/dist; ssh host:22. Remote Desktop uses vnc with target desktop for built-in local hosting, or host:5900 for an external server. Files requires tunnel Basic auth with a user. Remote Desktop strongly recommends it; without a user it needs agent_config.public_access_acknowledged true, otherwise the agent keeps it unavailable. The server allocates sni/public_url; do not send sni. tls_mode must be omitted or terminated (end-to-end TLS uses POST /api/v1/tunnels/{id}/e2e). Returns the first agent_token (kpt_\u2026) in plaintext shown once \u2014 save it before installing the agent. For Docker target networking see https://femtoport.com/docs/run-the-agent-with-docker.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TunnelCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created tunnel with plaintext agent_token (shown once)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelCreateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid json body, missing target, bad backend_mode/target shape, or tls_mode/cert_source set to anything other than terminated/shared_wildcard"
          },
          "403": {
            "description": "Unpaid-workspace tunnel-count limit reached"
          }
        },
        "operationId": "create_tunnel"
      }
    },
    "/api/v1/tunnels/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "Get tunnel",
        "responses": {
          "200": {
            "description": "Tunnel",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tunnel"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "get_tunnel"
      },
      "patch": {
        "summary": "Update tunnel",
        "responses": {
          "200": {
            "description": "Updated tunnel",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tunnel"
                }
              }
            }
          },
          "400": {
            "description": "Invalid json body, missing target, bad backend_mode/target shape, or tls_mode/cert_source set to anything other than terminated/shared_wildcard"
          },
          "404": {
            "description": "Not found"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TunnelUpdateRequest"
              }
            }
          }
        },
        "operationId": "update_tunnel",
        "description": "Update connection settings with target, or send only {name} for a metadata-only rename. Omitted name is preserved; an empty name clears the label. Renaming leaves routing, tokens, agents and access settings unchanged."
      },
      "delete": {
        "summary": "Delete tunnel",
        "responses": {
          "204": {
            "description": "Deleted"
          }
        },
        "operationId": "delete_tunnel"
      }
    },
    "/api/v1/tunnels/{id}/enabled": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Enable or disable a tunnel",
        "description": "Lighter than PATCH; propagates to the data plane sub-second. Body {\"enabled\": true|false}.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TunnelEnabledRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ tunnel_id, enabled }",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelEnabledResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "toggle_tunnel"
      }
    },
    "/api/v1/tunnels/{id}/e2e": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Enable or disable end-to-end TLS for a tunnel",
        "description": "Owner-only. Enabling switches the tunnel to passthrough + agent-managed ACME: the agent terminates public TLS with a Let's Encrypt certificate it obtains itself, and the private key never leaves the customer machine. Enabling requires the workspace's e2e_tls feature grant, no cert_worker custom domains attached to the tunnel (409 \u2014 agent_managed_acme custom domains are compatible), per-registered-domain issuance headroom (429), and a connected agent new enough to serve it (409). Disabling reverts to the shared wildcard. Body {\"enabled\": true|false}.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TunnelE2ERequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ tunnel_id, e2e_enabled, tls_mode, cert_source }",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelE2EResponse"
                }
              }
            }
          },
          "403": {
            "description": "Workspace lacks the e2e_tls feature grant"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Cert-worker custom domains attached, or connected agent too old"
          },
          "429": {
            "description": "Per-domain certificate issuance headroom exhausted; retry later"
          }
        },
        "operationId": "create_tunnels_e2e"
      }
    },
    "/api/v1/tunnels/{id}/tokens": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "List tunnel agent tokens",
        "responses": {
          "200": {
            "description": "Token list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelTokenListResponse"
                }
              }
            }
          }
        },
        "operationId": "list_tunnel_tokens"
      },
      "post": {
        "summary": "Issue tunnel agent token",
        "responses": {
          "201": {
            "description": "Created token with plaintext returned immediately and stored for email-code re-display",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelTokenIssueResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TunnelTokenIssueRequest"
              }
            }
          }
        },
        "operationId": "issue_tunnel_token"
      }
    },
    "/api/v1/tunnels/{id}/tokens/{token_id}/reveal/request": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "token_id",
          "in": "path",
          "required": true,
          "description": "Access-token id (session or machine token).",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Email an 8-digit code for viewing a stored tunnel token",
        "responses": {
          "202": {
            "description": "Reveal challenge created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenRevealRequestResponse"
                }
              }
            }
          },
          "404": {
            "description": "Tunnel or token not found"
          },
          "409": {
            "description": "This token predates stored-secret support and has no plaintext to re-display"
          },
          "429": {
            "description": "Rate limited"
          },
          "502": {
            "description": "Sending the reveal-code email failed"
          },
          "503": {
            "description": "Email delivery not configured"
          }
        },
        "operationId": "create_tunnels_tokens_reveal_request"
      }
    },
    "/api/v1/tunnels/{id}/tokens/{token_id}/reveal/verify": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "token_id",
          "in": "path",
          "required": true,
          "description": "Access-token id (session or machine token).",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Verify the 8-digit code and return the stored tunnel token",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TokenRevealVerifyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored token plaintext",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenRevealVerifyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad json, code not 8 digits, or invalid/expired/already-used code"
          }
        },
        "operationId": "create_tunnels_tokens_reveal_verify"
      }
    },
    "/api/v1/tunnels/{id}/tokens/{token_id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "token_id",
          "in": "path",
          "required": true,
          "description": "Access-token id (session or machine token).",
          "schema": {
            "type": "string"
          }
        }
      ],
      "delete": {
        "summary": "Revoke tunnel agent token",
        "responses": {
          "204": {
            "description": "Revoked"
          }
        },
        "operationId": "revoke_tunnel_token"
      }
    },
    "/api/v1/tunnels/{id}/agents": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "List connected agents for a tunnel",
        "responses": {
          "200": {
            "description": "Agent session list (router, connected_at, version)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectedAgentsResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "get_tunnels_agents"
      }
    },
    "/api/v1/tunnels/{id}/agent-update": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Ask the tunnel's agents to apply a pending self-update now",
        "description": "Bumps the server-owned apply counter; connected agents apply the staged update instead of waiting for their deferred window.",
        "responses": {
          "200": {
            "description": "Acknowledged"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Every connected agent on this tunnel is on a platform with no self-updater and would silently ignore the request (e.g. esp-idf)"
          }
        },
        "operationId": "create_tunnels_agent_update"
      }
    },
    "/api/v1/tunnels/{id}/agent-restart": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Ask the tunnel's agents to restart",
        "description": "Bumps the server-owned restart counter; connected agents restart their worker process.",
        "responses": {
          "200": {
            "description": "Acknowledged"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Every connected agent on this tunnel is on a platform with no self-updater and would silently ignore the request (e.g. esp-idf)"
          }
        },
        "operationId": "create_tunnels_agent_restart"
      }
    },
    "/api/v1/tunnels/{id}/access": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "Get a tunnel's basic-auth/MFA access-gate policy",
        "responses": {
          "200": {
            "description": "Access policy, including whether MFA is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelAccessPolicy"
                }
              }
            }
          }
        },
        "operationId": "get_tunnel_access"
      },
      "put": {
        "summary": "Replace a tunnel's access-gate policy",
        "description": "Body includes at least mfa_enabled; enabling MFA requires at least one access user already configured with a TOTP secret.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TunnelAccessPolicyUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated policy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelAccessPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Invalid policy, e.g. MFA enabled with no eligible access users"
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "update_tunnel_access"
      }
    },
    "/api/v1/tunnels/{id}/access/users": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Save a Basic auth user, updating an existing case-insensitive username",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TunnelAccessUserCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Access user created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelAccessPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Invalid username/password/TOTP secret, or resulting user does not meet MFA requirements"
          },
          "404": {
            "description": "Tunnel not found"
          },
          "200": {
            "description": "Existing user updated and activated; user_result identifies the committed mutation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelAccessPolicy"
                }
              }
            }
          }
        },
        "operationId": "create_tunnel_access_user",
        "description": "Creates a new user or updates and activates the existing username in this tunnel. Replaces the password; omitted MFA fields preserve protection. Concurrent saves serialize; the last committed password wins. Saved settings propagate automatically, but this response does not acknowledge remote agent application."
      }
    },
    "/api/v1/tunnels/{id}/access/users/{access_user_id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "access_user_id",
          "in": "path",
          "required": true,
          "description": "Tunnel access-gate user id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "summary": "Update a tunnel access user",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TunnelAccessUserPatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TunnelAccessPolicy"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "A Basic auth user with this case-insensitive username already exists."
          }
        },
        "operationId": "update_tunnel_access_user"
      },
      "delete": {
        "summary": "Disable a tunnel access user",
        "responses": {
          "204": {
            "description": "Disabled"
          },
          "404": {
            "description": "Not found or already disabled"
          }
        },
        "operationId": "delete_tunnel_access_user"
      }
    },
    "/api/v1/custom-domains": {
      "get": {
        "summary": "List workspace custom domains",
        "responses": {
          "200": {
            "description": "Custom domain list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomDomainListResponse"
                }
              }
            }
          }
        },
        "operationId": "list_custom_domains"
      },
      "post": {
        "summary": "Create a custom domain desired-state row",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomDomainCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created custom domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomDomain"
                }
              }
            }
          },
          "400": {
            "description": "Invalid hostname"
          },
          "404": {
            "description": "Requested tunnel not found"
          },
          "409": {
            "description": "Hostname or alias collision"
          }
        },
        "operationId": "create_custom_domain"
      }
    },
    "/api/v1/custom-domains/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "Get a custom domain",
        "responses": {
          "200": {
            "description": "Custom domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomDomain"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "get_custom_domain"
      },
      "patch": {
        "summary": "Update custom-domain desired state",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomDomainPatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated custom domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomDomain"
                }
              }
            }
          },
          "404": {
            "description": "Custom domain or tunnel not found"
          }
        },
        "operationId": "update_custom_domain"
      },
      "delete": {
        "summary": "Disable a custom domain",
        "responses": {
          "204": {
            "description": "Disabled"
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "delete_custom_domain"
      }
    },
    "/api/v1/custom-domains/{id}/verify": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Nudge DNS verification for a custom domain",
        "responses": {
          "200": {
            "description": "Verification queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomDomain"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "verify_custom_domain"
      }
    },
    "/api/v1/custom-domains/{id}/e2e": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Enable or disable end-to-end TLS for a custom domain",
        "description": "Owner-only and FREE. Enabling sets cert_source='agent_managed_acme': the customer's agent obtains and holds a Let's Encrypt certificate for the customer-owned hostname, edged pipes the raw ClientHello through, and the private key never leaves the customer machine. It is free because the certificate counts against the customer's own registered domain (not our shared pool) and passthrough is cheaper for us than cert-worker issuance \u2014 so there is no feature-grant check. Disabling reverts to the cert-worker flow (Femtoport issues and serves the cert; brief downtime while it is obtained), and is refused with 409 while the domain still points at a tunnel-level end-to-end (passthrough) tunnel. Body {\"enabled\": true|false}.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomDomainE2ERequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated custom domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomDomain"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Disable refused: domain still points at an end-to-end TLS tunnel"
          }
        },
        "operationId": "create_custom_domains_e2e"
      }
    },
    "/api/v1/custom-domains/{id}/retry-certificate": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Nudge certificate issuance retry for a custom domain",
        "responses": {
          "200": {
            "description": "Certificate retry queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomDomain"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "retry_custom_domain_certificate"
      }
    },
    "/api/v1/sessions": {
      "get": {
        "summary": "List browser sessions and API keys",
        "responses": {
          "200": {
            "description": "Access token list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionListResponse"
                }
              }
            }
          }
        },
        "operationId": "list_access_tokens",
        "description": "Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient."
      }
    },
    "/api/v1/api-keys": {
      "post": {
        "summary": "Create non-expiring machine API key",
        "description": "Browser-session only. The new key inherits the current session's workspace role. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/APIKeyCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created API key. Plaintext is returned once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIKeyCreateResponse"
                }
              }
            }
          },
          "403": {
            "description": "Called from a machine token or insufficient role"
          },
          "400": {
            "description": "Missing or too-long label"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_api_key"
      }
    },
    "/api/v1/sessions/{token_id}": {
      "parameters": [
        {
          "name": "token_id",
          "in": "path",
          "required": true,
          "description": "Access-token id (session or machine token).",
          "schema": {
            "type": "string"
          }
        }
      ],
      "delete": {
        "summary": "Revoke browser session or API key",
        "responses": {
          "204": {
            "description": "Revoked"
          },
          "404": {
            "description": "Not found"
          }
        },
        "operationId": "revoke_access_token",
        "description": "Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient."
      }
    },
    "/api/v1/account/mfa": {
      "get": {
        "summary": "Read account MFA status",
        "description": "Browser-session only. Returns whether MFA is enabled, active/pending factors, and remaining recovery-code count. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "MFA status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountMFAStatus"
                }
              }
            }
          },
          "403": {
            "description": "Machine token or non-browser session"
          }
        },
        "operationId": "get_account_mfa"
      }
    },
    "/api/v1/account/mfa/email/request": {
      "post": {
        "summary": "Request an MFA-enrollment email code",
        "description": "Browser-session only. Sends an 8-digit code to the account's current email address. Required before /api/v1/account/mfa/totp/start will provision a secret. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "202": {
            "description": "Code emailed; response includes challenge_id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountMFAEmailRequestResponse"
                }
              }
            }
          },
          "409": {
            "description": "MFA already enabled"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "operationId": "create_account_mfa_email_request"
      }
    },
    "/api/v1/account/mfa/email/verify": {
      "post": {
        "summary": "Verify an MFA-enrollment email code",
        "description": "Browser-session only. Body: { challenge_id, code }. On success returns a short-lived enroll_challenge_id ticket that /api/v1/account/mfa/totp/start consumes. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "enroll_challenge_id ticket",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountMFAEmailVerifyResponse"
                }
              }
            }
          },
          "403": {
            "description": "Invalid or expired code"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountMFAEmailVerifyRequest"
              }
            }
          }
        },
        "operationId": "create_account_mfa_email_verify"
      }
    },
    "/api/v1/account/mfa/totp/start": {
      "post": {
        "summary": "Start TOTP MFA enrollment",
        "description": "Browser-session only. Body: { enroll_challenge_id } from /api/v1/account/mfa/email/verify \u2014 proves live mailbox control before a secret is provisioned. Creates a pending TOTP factor and returns the secret plus otpauth URI. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Pending TOTP factor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountMFATOTPStartResponse"
                }
              }
            }
          },
          "403": {
            "description": "Email verification required"
          },
          "409": {
            "description": "MFA already enabled"
          },
          "503": {
            "description": "MFA unavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountMFATOTPStartRequest"
              }
            }
          }
        },
        "operationId": "create_account_mfa_totp_start"
      }
    },
    "/api/v1/account/mfa/totp/confirm": {
      "post": {
        "summary": "Confirm pending TOTP MFA enrollment",
        "description": "Browser-session only. Body: { factor_id, code }. Activates the factor and returns one-time recovery codes. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "MFA enrolled with recovery codes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountMFATOTPConfirmResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid code or request"
          },
          "404": {
            "description": "Pending factor not found"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountMFATOTPConfirmRequest"
              }
            }
          }
        },
        "operationId": "create_account_mfa_totp_confirm"
      }
    },
    "/api/v1/account/mfa/recovery-codes/regenerate": {
      "post": {
        "summary": "Regenerate MFA recovery codes",
        "description": "Browser-session only. Requires recent MFA verification on the current session. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "New recovery codes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountMFARecoveryCodesResponse"
                }
              }
            }
          },
          "403": {
            "description": "Recent MFA required"
          }
        },
        "operationId": "create_account_mfa_recovery_codes_regenerate"
      }
    },
    "/api/v1/account/mfa/disable": {
      "post": {
        "summary": "Disable account MFA",
        "description": "Browser-session only. Requires recent MFA verification, disables MFA factors, consumes recovery codes, and revokes other active browser sessions. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "204": {
            "description": "MFA disabled"
          },
          "403": {
            "description": "Recent MFA required"
          }
        },
        "operationId": "create_account_mfa_disable"
      }
    },
    "/api/v1/qr/svg": {
      "post": {
        "summary": "Render a QR code SVG",
        "description": "Authenticated helper used by the MFA enrollment UI. Body: { text }. The text must be an otpauth TOTP URI. Rendered in-process (no external service); returns image/svg+xml.",
        "responses": {
          "200": {
            "description": "SVG image"
          },
          "400": {
            "description": "Invalid request"
          },
          "413": {
            "description": "Payload too large"
          }
        },
        "operationId": "create_qr_svg"
      }
    },
    "/api/v1/account/delete/request": {
      "post": {
        "summary": "Request account deletion confirmation code",
        "description": "Browser session required; machine kpm_ tokens cannot delete or export the account and receive 403 Forbidden. Sends an 8-digit account deletion code to the account email. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "202": {
            "description": "Deletion challenge created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountDeleteRequestResponse"
                }
              }
            }
          },
          "403": {
            "description": "Machine token or non-browser session"
          },
          "404": {
            "description": "Account not found"
          }
        },
        "operationId": "request_account_delete"
      }
    },
    "/api/v1/account/delete": {
      "post": {
        "summary": "Confirm account deletion",
        "description": "Deletes the authenticated person's account after emailed-code confirmation. Personal sessions, API keys and memberships are removed across all workspaces. Workspace credit, entitlement and pending accounting are preserved. Shared workspaces with another active owner are unchanged, including their workspace-owned agent credentials; remaining owners can revoke those in tunnel settings. Workspaces losing their last active owner stop serving and their tunnel configuration is retired. Personal cleanup begins after 30 days. Unresolved workspace cases may require review; retained records follow the Privacy Notice. A new account does not restore old access. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountDeleteConfirmRequest"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Account deleted; no response body"
          },
          "400": {
            "description": "Bad JSON or missing challenge_id/code"
          },
          "403": {
            "description": "Machine token, invalid or expired challenge, wrong code, attempt-capped code, or wrong challenge purpose"
          }
        },
        "operationId": "confirm_account_delete"
      }
    },
    "/api/v1/account/export": {
      "get": {
        "summary": "Download account data export",
        "description": "Requires an email-verified identity session. A workspace API key or a session obtained from one receives 403. Returns an application/json attachment with the account data and visible audit events. Audit source IPs are included for the caller's own events. Each gateway replica limits export requests per user.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account export JSON attachment",
            "headers": {
              "Content-Disposition": {
                "description": "Attachment filename in the form femtoport-export-<user_id>-<YYYYMMDD>.json",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountExport"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Email-verified identity session required"
          },
          "404": {
            "description": "Account not found"
          },
          "429": {
            "description": "Export rate limit reached"
          },
          "503": {
            "description": "Export could not finish. Retry the request."
          }
        },
        "operationId": "export_account"
      }
    },
    "/api/v1/audit": {
      "get": {
        "summary": "List audit events",
        "responses": {
          "200": {
            "description": "Audit event page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad since/until (must be RFC3339), action filter contains %, _, or \\\\, or bad cursor"
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "until",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "action",
            "in": "query",
            "description": "Substring match, not a glob; %, _, and \\\\ are rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "resource_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque value from a previous response's next_cursor.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "operationId": "list_audit"
      }
    },
    "/api/v1/management/events": {
      "get": {
        "summary": "SSE stream for UI state sync",
        "description": "Server-sent events stream for UI state sync.",
        "responses": {
          "200": {
            "description": "text/event-stream. `event: sync\\ndata: <workspace event type or \"tick <ms>\">\\n\\n` on every workspace change or the 30s fallback tick. The server closes the stream after ~55s so the client reconnects (EventSource does this automatically)."
          }
        },
        "operationId": "get_management_events"
      }
    },
    "/api/v1/billing/products": {
      "get": {
        "summary": "List billing products",
        "responses": {
          "200": {
            "description": "Product list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductsListResponse"
                }
              }
            }
          },
          "503": {
            "description": "Billing not configured"
          },
          "502": {
            "description": "Provider catalog unavailable"
          }
        },
        "operationId": "list_billing_products"
      }
    },
    "/api/v1/billing/portal": {
      "post": {
        "summary": "Open the buyer's Creem billing portal",
        "description": "Uses the authenticated user's verified account email. The returned short-lived URL opens Creem's portal for viewing purchases and canceling subscriptions. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "responses": {
          "200": {
            "description": "Billing portal URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "url"
                  ],
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No Creem customer found for this account email"
          },
          "502": {
            "description": "Billing provider unavailable"
          },
          "503": {
            "description": "Billing not configured"
          }
        },
        "operationId": "open_billing_portal"
      }
    },
    "/api/v1/billing/checkouts": {
      "post": {
        "summary": "Create checkout",
        "responses": {
          "200": {
            "description": "Checkout URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateCheckoutResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad json or missing product_id"
          },
          "503": {
            "description": "Billing not configured, or product not configured on this operator's catalog"
          },
          "502": {
            "description": "Billing provider unavailable"
          },
          "202": {
            "description": "Create outcome or private payment link remains pending; retry the SAME operation_id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateCheckoutResponse"
                }
              }
            }
          },
          "409": {
            "description": "Operation ID was reused for a different workspace, actor or product"
          },
          "429": {
            "description": "Checkout attempt rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCheckoutRequest"
              }
            }
          }
        },
        "operationId": "create_checkout",
        "description": "Current active verified owner only. Persist an immutable purchase intent/offer snapshot under the workspace closure barrier before external creation. At most one acknowledged caller dispatches for each stable operation_id. Concurrent/replayed/ambiguous creates never automatically dispatch again. Provider request_id tracks the server intent; provider-side idempotency is not assumed. Hosted links are scope-encrypted and retained 24h independently of financial obligations. Reuse operation_id to check an interrupted or pending request. A new operation_id starts a separate purchase; it does not cancel earlier requests, which may still complete. Unrelated purchases are not blocked by unresolved provider outcomes. Unknown outcomes remain retained; there is no automatic create redispatch or payment-link recovery promise. No-store response; requests are rate-limited."
      }
    },
    "/api/v1/billing/checkouts/verify": {
      "post": {
        "summary": "Verify a returned checkout and enqueue credit",
        "description": "Owner-only. Requires the local checkout binding and frozen owner authority. Checks provider paid order and intent, enqueues the same durable paid-event path, and reports credited only from that exact immutable order record. Other workspace balance changes never prove purchase completion. Private response is no-store.",
        "responses": {
          "200": {
            "description": "Exact order credited, or queued for processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyCheckoutResponse"
                }
              }
            }
          },
          "202": {
            "description": "Not yet paid, or not the caller's checkout \u2014 keep polling",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyCheckoutResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad json or missing checkout_id"
          },
          "503": {
            "description": "Billing not configured"
          },
          "403": {
            "description": "Frozen checkout authority revoked"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyCheckoutRequest"
              }
            }
          }
        },
        "operationId": "create_billing_checkouts_verify"
      }
    },
    "/api/v1/billing/codes/redeem": {
      "post": {
        "summary": "Redeem a capability code",
        "description": "Owner-only. Applies every capability the code carries to the current workspace: credit tops up credit_bytes/entitlement_seconds, feature grants the named workspace feature. Returns a summary of what was applied and the new balance.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RedeemCodeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ applied: { credit_bytes?, entitlement_seconds?, features? }, new_balance_bytes? }",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RedeemCodeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid, expired, exhausted, revoked, or wrong-email code"
          },
          "403": {
            "description": "Not the workspace owner"
          }
        },
        "operationId": "redeem_code"
      }
    },
    "/api/v1/invites": {
      "get": {
        "summary": "List your invite codes",
        "description": "Returns the caller's own single-use invite codes newest-first, each with its status, validity, and redemption list, plus the pending-invite quota envelope. Any workspace member (owner/admin/member) may call. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "responses": {
          "200": {
            "description": "{ invites: [{ code_id, code, share_url, status, bound_email?, note?, max_uses, used_count, valid_until?, created_at, redemptions: [{ email, redeemed_at }] }], quota, used_slots, enabled }",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvitesListResponse"
                }
              }
            }
          }
        },
        "operationId": "get_invites"
      },
      "post": {
        "summary": "Mint an invite code",
        "description": "Mints a single-use code carrying the register capability, owned by the caller, that admits one new person during invite-only registration. Any workspace member (owner/admin/member) may call. Fails with 403 invites_disabled when the operator has turned the surface off, or 429 invite_quota_reached when the caller is at their pending-invite limit. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InviteCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "{ code_id, code, share_url, status, bound_email?, note?, max_uses, used_count, valid_until?, created_at, redemptions }",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invite"
                }
              }
            }
          },
          "400": {
            "description": "Invalid bound_email or note too long"
          },
          "403": {
            "description": "Invites are disabled (invites_disabled)"
          },
          "429": {
            "description": "Pending-invite quota reached (invite_quota_reached)"
          }
        },
        "operationId": "create_invites"
      }
    },
    "/api/v1/invites/{id}/revoke": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "Revoke one of your invite codes",
        "description": "Disables one of the caller's own invites so it can no longer admit a signup. Scoped to created_by_user_id: an unknown, already-revoked, or someone-else's code returns 404. Any workspace member (owner/admin/member) may call. Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient.",
        "responses": {
          "200": {
            "description": "{ code_id, status: \"revoked\" }"
          },
          "404": {
            "description": "Not found or already revoked (not_found)"
          }
        },
        "operationId": "create_invites_revoke"
      }
    },
    "/api/v1/free-trial/activate": {
      "post": {
        "summary": "Activate free trial",
        "description": "Requires a valid Cloudflare Turnstile token for action free_trial_activate, bound to this portal hostname, and approved by server-side Siteverify.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FreeTrialActivateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Trial activated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeTrialActivateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad json or missing turnstile_token"
          },
          "401": {
            "description": "Not authenticated"
          },
          "403": {
            "description": "Captcha rejected (score below threshold)"
          },
          "409": {
            "description": "Free trial already claimed"
          },
          "502": {
            "description": "Captcha check failed"
          },
          "503": {
            "description": "Captcha not configured, or free trial product not configured"
          }
        },
        "operationId": "activate_free_trial"
      }
    },
    "/api/v1/legal/current": {
      "get": {
        "summary": "Get dated legal releases and acceptance state",
        "responses": {
          "200": {
            "description": "Current Terms and Privacy release dates, accepted dates, and whether acceptance is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegalCurrent"
                }
              }
            }
          }
        },
        "operationId": "get_legal_current"
      }
    },
    "/api/v1/legal/accept": {
      "post": {
        "summary": "Accept the current dated Terms and Privacy releases",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tos_release_date",
                  "privacy_release_date"
                ],
                "properties": {
                  "tos_release_date": {
                    "type": "string",
                    "format": "date",
                    "example": "2026-07-15"
                  },
                  "privacy_release_date": {
                    "type": "string",
                    "format": "date",
                    "example": "2026-07-15"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Accepted"
          },
          "409": {
            "description": "A newer release must be loaded"
          },
          "403": {
            "description": "Legal acceptance requires an interactive browser session; machine kpm_ tokens are rejected"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "accept_legal",
        "description": "Requires email-verified account sign-in. A workspace API key or a session obtained from one is insufficient."
      }
    },
    "/api/v1/legal/text/{kind}/{releaseDate}": {
      "parameters": [
        {
          "name": "kind",
          "in": "path",
          "required": true,
          "description": "Legal document kind (tos | privacy | dpa | notice).",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "releaseDate",
          "in": "path",
          "required": true,
          "description": "Dated release, YYYY-MM-DD.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "Public legal document text",
        "security": [],
        "responses": {
          "200": {
            "description": "HTML body"
          }
        },
        "operationId": "get_legal_text_by_kind_releaseDate"
      }
    },
    "/api/v1/legal/text/{kind}": {
      "parameters": [
        {
          "name": "kind",
          "in": "path",
          "required": true,
          "description": "Legal document kind (tos | privacy | dpa | notice).",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "Public legal document text, latest version",
        "security": [],
        "responses": {
          "200": {
            "description": "HTML body"
          }
        },
        "operationId": "get_legal_text_by_kind"
      }
    },
    "/api/v1/agent-release": {
      "get": {
        "summary": "Current agent release manifest and download URLs",
        "responses": {
          "200": {
            "description": "Release info"
          }
        },
        "operationId": "get_agent_release"
      }
    },
    "/api/v1/tls-advanced-interest": {
      "post": {
        "summary": "Register interest in advanced TLS features",
        "responses": {
          "204": {
            "description": "Recorded"
          }
        },
        "operationId": "create_tls_advanced_interest"
      }
    },
    "/api/v1/admin/admins": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "List platform admins",
        "responses": {
          "200": {
            "description": "Admin list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformAdminListResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "get_admin_admins"
      },
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Reject platform-admin mutation",
        "description": "Platform admins are code-configured; DB/API mutations do not grant authority.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "405": {
            "description": "Platform admins are code-configured"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_admin_admins"
      }
    },
    "/api/v1/admin/admins/{user_id}": {
      "parameters": [
        {
          "name": "user_id",
          "in": "path",
          "required": true,
          "description": "Platform user id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "delete": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Reject platform-admin removal",
        "description": "Platform admins are code-configured; DB/API mutations do not revoke authority.",
        "responses": {
          "405": {
            "description": "Platform admins are code-configured"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "delete_admin_admins"
      }
    },
    "/api/v1/admin/stats": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Get platform-admin telemetry statistics",
        "description": "Full status snapshot. The e2e_tls block reports end-to-end TLS adoption: activations_7d (mgmt.tunnels_archive rows with archived_reason='e2e_enabled' in the trailing 7 days \u2014 the true activation count, surviving a later disable), active_tunnels (tunnels currently on tls_mode='passthrough'), custom_domains_free (custom domains on the free per-domain path, cert_source='agent_managed_acme'), issuance_headroom_limit (the per-domain enable-guard cap), and pool_domains[] (per unpaid_pool registered domain: base_domain, used = live agent-managed tunnels inside the issuance window matching the enable guard's own count, and limit).",
        "responses": {
          "200": {
            "description": "Platform stats",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminStats"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "get_admin_stats"
      }
    },
    "/api/v1/admin/status": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Full platform status (authenticated equivalent of /status)",
        "responses": {
          "200": {
            "description": "Status snapshot"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "get_admin_status"
      }
    },
    "/api/v1/admin/events": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Recent platform admin event log",
        "responses": {
          "200": {
            "description": "Event list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminEventsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad since, wildcard characters in type, or bad cursor"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Substring match on action; %, _, and \\\\ are rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "severity",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source_app",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "result",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "workspace_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "operationId": "get_admin_events"
      }
    },
    "/api/v1/admin/events/stream": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "SSE stream of platform admin events",
        "description": "text/event-stream; distinct from the customer-scoped GET /api/v1/management/events stream.",
        "responses": {
          "200": {
            "description": "text/event-stream of admin events. Each frame is `event: audit\\ndata: <AdminEventItem JSON>\\n\\n`; a bare `: keepalive` comment line is sent when nothing new has landed."
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "get_admin_events_stream"
      }
    },
    "/api/v1/admin/users/{user_id}/subscriptions": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Get known subscriptions for a user from Creem",
        "description": "Returns subscriptions linked to checkouts initiated by this user. Provider errors or truncation set unavailable; an empty list does not establish that Creem has no other subscriptions.",
        "operationId": "get_admin_user_subscriptions",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Provider observations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "subscriptions",
                    "unavailable"
                  ],
                  "properties": {
                    "unavailable": {
                      "type": "boolean"
                    },
                    "subscriptions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "status",
                          "product",
                          "current_period_end_date",
                          "next_transaction_date"
                        ],
                        "properties": {
                          "status": {
                            "type": "string"
                          },
                          "product": {
                            "type": "string"
                          },
                          "current_period_end_date": {
                            "type": "string"
                          },
                          "next_transaction_date": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Subscription lookup unavailable"
          }
        }
      }
    },
    "/api/v1/admin/users": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "List platform users",
        "responses": {
          "200": {
            "description": "User list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUserListResponse"
                }
              }
            }
          },
          "400": {
            "description": "limit/offset/q out of range"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Free-text search over the fields noted in the summary/description.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "operationId": "get_admin_users"
      }
    },
    "/api/v1/admin/workspaces": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "List platform workspaces",
        "responses": {
          "200": {
            "description": "Workspace list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminWorkspaceListResponse"
                }
              }
            }
          },
          "400": {
            "description": "limit/offset/q out of range"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Free-text search over the fields noted in the summary/description.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "operationId": "get_admin_workspaces"
      }
    },
    "/api/v1/admin/tunnels": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "List all tunnels",
        "responses": {
          "200": {
            "description": "Tunnel list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminTunnelListResponse"
                }
              }
            }
          },
          "400": {
            "description": "limit/offset/q out of range"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Free-text search over the fields noted in the summary/description.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "operationId": "get_admin_tunnels"
      }
    },
    "/api/v1/admin/grants": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "List grant history",
        "responses": {
          "200": {
            "description": "Grant list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminGrantListResponse"
                }
              }
            }
          },
          "400": {
            "description": "limit/offset/q out of range"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Free-text search over the fields noted in the summary/description.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "operationId": "get_admin_grants"
      }
    },
    "/api/v1/admin/tunnels/{id}/rproxy-domain": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Resource id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Migrate a tunnel to a reverse-proxy domain",
        "responses": {
          "200": {
            "description": "Migrated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminRProxyMigrateResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminRProxyMigrateRequest"
              }
            }
          }
        },
        "operationId": "create_admin_tunnels_rproxy_domain"
      }
    },
    "/api/v1/admin/alerts": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Current Alertmanager alerts",
        "responses": {
          "200": {
            "description": "Alert list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminAlertsResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "get_admin_alerts"
      }
    },
    "/api/v1/admin/logs": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Query recent platform logs",
        "responses": {
          "200": {
            "description": "Log lines",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminLogsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad minutes or limit"
          },
          "502": {
            "description": "LogsQL query rejected or the log store returned an error"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "minutes",
            "in": "query",
            "description": "Lookback window. VictoriaLogs retention is 14 days.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10080,
              "default": 15
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 200
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "LogsQL filter, passed through verbatim.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "container",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "operationId": "get_admin_logs"
      }
    },
    "/api/v1/admin/logs/containers": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "List log container names",
        "responses": {
          "200": {
            "description": "Container name list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminLogContainersResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "get_admin_logs_containers"
      }
    },
    "/api/v1/admin/logs/stream": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Live platform log stream (SSE)",
        "responses": {
          "200": {
            "description": "text/event-stream tail of matching log lines. `event: log\\ndata: <AdminLogEntry JSON>\\n\\n` per line; `event: error` if VictoriaLogs disconnects."
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "container",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "operationId": "get_admin_logs_stream"
      }
    },
    "/api/v1/admin/metrics/panels": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Metric panel catalog for the admin graphs",
        "responses": {
          "200": {
            "description": "Panel groups and panel definitions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricPanelsResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "get_admin_metrics_panels"
      }
    },
    "/api/v1/admin/metrics/range": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Metric range query for one panel",
        "responses": {
          "200": {
            "description": "Time series for the requested panel and range",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricRangeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Unknown panel or bad window"
          },
          "502": {
            "description": "Metrics store unavailable"
          },
          "503": {
            "description": "Database or metrics store not configured for this panel's source"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "panel",
            "in": "query",
            "required": true,
            "description": "A panel id from GET /admin/metrics/panels.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "window",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "15m",
                "1h",
                "6h",
                "24h",
                "7d"
              ],
              "default": "1h"
            }
          }
        ],
        "operationId": "get_admin_metrics_range"
      }
    },
    "/api/v1/admin/takedowns": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "List takedown requests",
        "responses": {
          "200": {
            "description": "Takedown list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminTakedownListResponse"
                }
              }
            }
          },
          "400": {
            "description": "limit/offset/q out of range"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Free-text search over the fields noted in the summary/description.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "operationId": "get_admin_takedowns"
      }
    },
    "/api/v1/admin/users/{user_id}/suspend": {
      "parameters": [
        {
          "name": "user_id",
          "in": "path",
          "required": true,
          "description": "Platform user id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Suspend platform user",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminReasonRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User suspended"
          },
          "404": {
            "description": "Not found"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_admin_users_suspend"
      }
    },
    "/api/v1/admin/users/{user_id}/activate": {
      "parameters": [
        {
          "name": "user_id",
          "in": "path",
          "required": true,
          "description": "Platform user id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Activate platform user",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminReasonRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User activated"
          },
          "404": {
            "description": "Not found"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_admin_users_activate"
      }
    },
    "/api/v1/admin/workspaces/{workspace_id}/suspend": {
      "parameters": [
        {
          "name": "workspace_id",
          "in": "path",
          "required": true,
          "description": "Workspace id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Suspend workspace",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminReasonRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Workspace suspended"
          },
          "404": {
            "description": "Not found"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_admin_workspaces_suspend"
      }
    },
    "/api/v1/admin/workspaces/{workspace_id}/activate": {
      "parameters": [
        {
          "name": "workspace_id",
          "in": "path",
          "required": true,
          "description": "Workspace id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Activate workspace",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminReasonRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Workspace activated"
          },
          "404": {
            "description": "Not found"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_admin_workspaces_activate"
      }
    },
    "/api/v1/admin/workspaces/{workspace_id}/grants": {
      "parameters": [
        {
          "name": "workspace_id",
          "in": "path",
          "required": true,
          "description": "Workspace id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Issue workspace grant",
        "description": "Manual negative adjustments may remove only unissued traffic capacity when a spending-rights wallet exists. Byte credits are perpetual; entitlement_days changes admission entitlement separately. Rejected adjustments create no grant or successful-grant audit event.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminGrantIssueRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Grant issued"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Negative adjustment would remove issued traffic rights; no grant is inserted.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_admin_workspaces_grants"
      }
    },
    "/api/v1/admin/workspaces/{workspace_id}/tokens": {
      "parameters": [
        {
          "name": "workspace_id",
          "in": "path",
          "required": true,
          "description": "Workspace id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Mint a machine API token for a user in a workspace",
        "description": "Platform-admin session only. Creates or updates the user's active workspace membership for the requested role, returns the plaintext kpm_ token once, and writes an operator audit event.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "user_id",
                  "role",
                  "reason"
                ],
                "properties": {
                  "user_id": {
                    "type": "string"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "member",
                      "viewer"
                    ]
                  },
                  "label": {
                    "type": "string",
                    "maxLength": 80
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 500
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Token minted. Plaintext api_token is returned once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminTokenMintResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "404": {
            "description": "Active user/workspace pair not found"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_admin_workspaces_tokens"
      }
    },
    "/api/v1/admin/takedowns/{request_id}/action": {
      "parameters": [
        {
          "name": "request_id",
          "in": "path",
          "required": true,
          "description": "Takedown request id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Take action on a takedown request",
        "responses": {
          "200": {
            "description": "Action applied"
          },
          "404": {
            "description": "Not found"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_admin_takedowns_action"
      }
    },
    "/api/v1/admin/takedowns/{request_id}/dismiss": {
      "parameters": [
        {
          "name": "request_id",
          "in": "path",
          "required": true,
          "description": "Takedown request id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Dismiss a takedown request",
        "responses": {
          "204": {
            "description": "Request dismissed"
          },
          "404": {
            "description": "Not found"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_admin_takedowns_dismiss"
      }
    },
    "/api/v1/admin/codes": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "List capability codes",
        "description": "Paginated list of codes with their capabilities, usage, binding, validity window, and revocation state. Supports ?q= search over code, label, note, and bound email.",
        "responses": {
          "200": {
            "description": "Code list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminCodeListResponse"
                }
              }
            }
          },
          "400": {
            "description": "limit/offset/q out of range"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Free-text search over the fields noted in the summary/description.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "operationId": "get_admin_codes"
      },
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Mint a capability code",
        "description": "Creates a code carrying one or more capabilities: `register` (bypass invite-only signup), `credit` (credit_bytes and/or entitlement_seconds), `feature` (feature_name, e.g. e2e_tls). Body: { capabilities: [{ capability, credit_bytes?, entitlement_seconds?, feature_name? }], bound_email?, valid_from?, valid_until?, max_uses (default 1), label?, note? }. At least one capability is required. Returns the generated code.",
        "responses": {
          "201": {
            "description": "Code created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminCode"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters or no capabilities"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdminCodeCreateRequest"
              }
            }
          }
        },
        "operationId": "create_admin_codes"
      }
    },
    "/api/v1/admin/codes/{code_id}/revoke": {
      "parameters": [
        {
          "name": "code_id",
          "in": "path",
          "required": true,
          "description": "Capability code id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Revoke a capability code",
        "description": "Sets revoked_at so the code can no longer be redeemed. Idempotent target state; already-revoked or unknown codes return 404.",
        "responses": {
          "200": {
            "description": "Code revoked"
          },
          "404": {
            "description": "Not found or already revoked"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "operationId": "create_admin_codes_revoke"
      }
    },
    "/api/v1/admin/waitlist": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "List launch-waitlist signups",
        "description": "Paginated list of waitlist entries (email, source, joined and notified timestamps). Supports ?q= search over email and source. Pass ?format=csv for a CSV export download instead of the JSON page.",
        "responses": {
          "200": {
            "description": "Waitlist entries (JSON page, or a CSV attachment when ?format=csv is set)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminWaitlistListResponse"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "Content-Disposition": {
                "description": "Present only on the ?format=csv response: attachment; filename=\"waitlist.csv\"",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "limit/offset/q out of range"
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Free-text search over the fields noted in the summary/description.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "format",
            "in": "query",
            "description": "Set to csv to stream the full list (up to 100000 rows) as text/csv instead of the paginated JSON envelope.",
            "schema": {
              "type": "string",
              "enum": [
                "csv"
              ]
            }
          }
        ],
        "operationId": "get_admin_waitlist"
      }
    },
    "/api/v1/billing/creem-webhook": {
      "post": {
        "summary": "Creem billing webhook receiver",
        "description": "Verifies the Creem webhook signature and records the raw event for the reconciler. Not a customer-facing endpoint. Creem is the only hosted-checkout provider.",
        "security": [],
        "responses": {
          "200": {
            "description": "Event recorded (idempotent) \u2014 this does NOT mean credit was applied; mgmt-reconciler consumes the row asynchronously"
          },
          "400": {
            "description": "Unreadable body, missing creem-signature header, bad json, or missing event id/type"
          },
          "401": {
            "description": "HMAC signature verification failed"
          },
          "503": {
            "description": "Billing webhooks not configured (no webhook secret set)"
          }
        },
        "operationId": "create_billing_creem_webhook"
      }
    },
    "/api/v1/email/ses-sns-webhook": {
      "post": {
        "summary": "Amazon SES feedback webhook",
        "description": "Verifies SNS signature and topic, then records a minimal feedback summary without changing delivery or account state.",
        "security": [],
        "responses": {
          "200": {
            "description": "SNS notification accepted or ignored"
          },
          "403": {
            "description": "SNS signature or topic rejected"
          },
          "410": {
            "description": "SES SNS feedback not configured"
          },
          "400": {
            "description": "Failed to read the request body, or the SNS envelope is malformed"
          }
        },
        "operationId": "create_email_ses_sns_webhook"
      }
    },
    "/api/v1/email/zeptomail-webhook": {
      "post": {
        "summary": "ZeptoMail feedback webhook",
        "description": "Receives provider-signed email feedback and records a minimal event summary without changing delivery or account state.",
        "security": [],
        "responses": {
          "200": {
            "description": "Verified feedback recorded or already seen"
          },
          "400": {
            "description": "Malformed request"
          },
          "403": {
            "description": "Signature rejected"
          },
          "503": {
            "description": "Feedback is unavailable or could not be recorded"
          }
        },
        "operationId": "create_email_zeptomail_webhook"
      }
    },
    "/api/v1/feedback": {
      "post": {
        "summary": "Send management feedback to Femtoport",
        "operationId": "send_feedback",
        "description": "Authenticated; all workspace roles and both session and machine tokens may send. Requires current legal acceptance. Queues mail to the configured operator recipient, using server-derived registered email, user ID, current workspace ID and role. Requests are rate-limited. Client identity and recipient fields do not control attribution or delivery.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeedbackRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued for email delivery, not yet delivered.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, empty/oversized message, or missing account-sharing acknowledgement."
          },
          "401": {
            "description": "Missing or invalid credentials."
          },
          "403": {
            "description": "Insufficient workspace role."
          },
          "428": {
            "description": "Current legal acceptance required."
          },
          "429": {
            "description": "Per-user sending limit reached.",
            "headers": {
              "Retry-After": {
                "description": "Seconds before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "500": {
            "description": "Account lookup or email enqueue failed."
          },
          "503": {
            "description": "Feedback recipient or sender is not configured."
          }
        }
      }
    },
    "/api/v1/referrals": {
      "get": {
        "operationId": "get_referrals",
        "summary": "Get your reusable public referral link and attributed registration count",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Personal referral details; no automatic rewards.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/agent-router-policies/{scope}/{id}": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Preview scoped agent-router policy",
        "description": "Platform-admin session only. Audited configuration snapshot; eligibility intersects workspace/tunnel policies and global maintenance. Does not assert live availability. Workspace preview excludes individual tunnel restrictions. expected_version=0 requires absence. Traffic authorization is separate: lifecycle_allows_traffic reports workspace/tunnel/route configuration, and does not filter placement IDs or assert credit or live health.",
        "operationId": "preview_admin_agent_router_policy",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "scope",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "workspace",
                "tunnel"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audited configuration snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "policy": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "policy_id": {
                          "type": "string"
                        },
                        "workspace_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "tunnel_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "allowed_router_ids": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          }
                        },
                        "denied_router_ids": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "starts_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "expires_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "reason": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "eligible_router_ids": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "basis": {
                      "type": "string",
                      "enum": [
                        "configuration_snapshot"
                      ]
                    },
                    "evaluated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "scope": {
                      "type": "string"
                    },
                    "scope_id": {
                      "type": "string"
                    },
                    "lifecycle_allows_traffic": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid policy or unknown router"
          },
          "403": {
            "description": "Platform admin session required"
          },
          "404": {
            "description": "Scope not found"
          },
          "409": {
            "description": "Version conflict"
          }
        }
      },
      "put": {
        "tags": [
          "Admin"
        ],
        "summary": "Apply scoped agent-router policy",
        "description": "Platform-admin session only. Audited configuration snapshot; eligibility intersects workspace/tunnel policies and global maintenance. Does not assert live availability. Workspace preview excludes individual tunnel restrictions. expected_version=0 requires absence. Traffic authorization is separate: lifecycle_allows_traffic reports workspace/tunnel/route configuration, and does not filter placement IDs or assert credit or live health.",
        "operationId": "apply_admin_agent_router_policy",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "scope",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "workspace",
                "tunnel"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audited configuration snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "policy": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "policy_id": {
                          "type": "string"
                        },
                        "workspace_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "tunnel_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "allowed_router_ids": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          }
                        },
                        "denied_router_ids": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "starts_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "expires_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "reason": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "eligible_router_ids": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "basis": {
                      "type": "string",
                      "enum": [
                        "configuration_snapshot"
                      ]
                    },
                    "evaluated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "scope": {
                      "type": "string"
                    },
                    "scope_id": {
                      "type": "string"
                    },
                    "lifecycle_allows_traffic": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid policy or unknown router"
          },
          "403": {
            "description": "Platform admin session required"
          },
          "404": {
            "description": "Scope not found"
          },
          "409": {
            "description": "Version conflict"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason",
                  "expected_version"
                ],
                "properties": {
                  "allowed_router_ids": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "description": "Null is default allow; [] requires suspend_all=true."
                  },
                  "denied_router_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "starts_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  },
                  "expires_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "Must expire within 24 hours; null permits permanent policy."
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500
                  },
                  "expected_version": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "suspend_all": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Admin"
        ],
        "summary": "Delete scoped agent-router policy",
        "description": "Platform-admin session only. Audited configuration snapshot; eligibility intersects workspace/tunnel policies and global maintenance. Does not assert live availability. Workspace preview excludes individual tunnel restrictions. expected_version=0 requires absence. Traffic authorization is separate: lifecycle_allows_traffic reports workspace/tunnel/route configuration, and does not filter placement IDs or assert credit or live health.",
        "operationId": "delete_admin_agent_router_policy",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "scope",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "workspace",
                "tunnel"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audited configuration snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "policy": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "policy_id": {
                          "type": "string"
                        },
                        "workspace_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "tunnel_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "allowed_router_ids": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          }
                        },
                        "denied_router_ids": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "starts_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "expires_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "reason": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "eligible_router_ids": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "basis": {
                      "type": "string",
                      "enum": [
                        "configuration_snapshot"
                      ]
                    },
                    "evaluated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "scope": {
                      "type": "string"
                    },
                    "scope_id": {
                      "type": "string"
                    },
                    "lifecycle_allows_traffic": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid policy or unknown router"
          },
          "403": {
            "description": "Platform admin session required"
          },
          "404": {
            "description": "Scope not found"
          },
          "409": {
            "description": "Version conflict"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason",
                  "expected_version"
                ],
                "properties": {
                  "allowed_router_ids": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "description": "Null is default allow; [] requires suspend_all=true."
                  },
                  "denied_router_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "starts_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  },
                  "expires_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "Must expire within 24 hours; null permits permanent policy."
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500
                  },
                  "expected_version": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "suspend_all": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/registration": {
      "get": {
        "operationId": "get_auth_registration",
        "summary": "Read the verified new-user registration step",
        "description": "Requires the opaque registration cookie set after email verification. No workspace authority. Returns registration_required=false when absent/expired. Response is not cached.",
        "security": [],
        "responses": {
          "200": {
            "description": "registration_required, email, referral_code, invite_required, invite_provided and registration_unavailable for a valid proof."
          },
          "503": {
            "description": "Registration state unavailable"
          }
        }
      },
      "post": {
        "operationId": "create_auth_registration",
        "summary": "Create an account after identity verification",
        "description": "Requires the Secure HttpOnly registration cookie. The proof, account creation, optional referral attribution and invitation redemption are committed atomically. Admission uses the current registration policy. Per-IP auth rate limit applies. Existing accounts discovered concurrently sign in instead; MFA remains required where configured.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "Invite code; required when registration is invite-only unless the proof already carries a valid invitation."
                  },
                  "referral_code": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "Optional public referral code for open registration."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session cookie set; redirect contains the surviving management intent."
          },
          "202": {
            "description": "MFA required; includes mfa_challenge_id and methods."
          },
          "400": {
            "description": "Invalid request or invitation."
          },
          "403": {
            "description": "access_required: valid registration invitation required; proof stays available for retry. Also rejects a foreign browser Origin."
          },
          "410": {
            "description": "Proof used or expired; start sign-in again."
          },
          "429": {
            "description": "Rate limited."
          },
          "503": {
            "description": "Service temporarily at capacity or unavailable. Retry later; additional customer credit does not resolve service capacity.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "service_capacity_unavailable for exhausted service capacity."
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/refund-cases": {
      "get": {
        "summary": "List pending refund adjustment cases",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current pending cases, earliest review first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RefundCase"
                      }
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Platform admin session required"
          },
          "503": {
            "description": "Status unavailable"
          }
        }
      }
    },
    "/api/v1/admin/refund-cases/{case_id}/review": {
      "post": {
        "summary": "Record an idempotent operator review and queue owner update",
        "parameters": [
          {
            "name": "case_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefundCaseReviewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Original review promise, also on same-operation replay",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "operation_id": {
                      "type": "string"
                    },
                    "review_sequence": {
                      "type": "integer"
                    },
                    "next_update_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "review_due_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "403": {
            "description": "Platform admin session required"
          },
          "409": {
            "description": "Changed case, operation mismatch or deadline outside 24 hours"
          },
          "503": {
            "description": "Retry same operation_id; outcome can be uncertain"
          }
        }
      }
    },
    "/api/v1/closing-receipts/{receipt_id}/read": {
      "post": {
        "summary": "Read a narrow closing traffic receipt",
        "description": "Capability-authorized; no normal sign-in or workspace access. Send the secret in the JSON body. Response is no-store. Decimal byte counts are strings. Traffic settlement is separate from provider/refund finality and is not a final invoice. Rate-limited.",
        "security": [],
        "parameters": [
          {
            "name": "receipt_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "retrieval_key"
                ],
                "properties": {
                  "retrieval_key": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authorized cutoff and pinned late proof",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "receipt_id",
                    "cutoff_at",
                    "access_expires_at",
                    "credit_bytes_at_cut",
                    "confirmed_usage_bytes_at_cut",
                    "confirmed_usage_bytes_including_late_proof",
                    "pending_traffic_obligations",
                    "recovery_available_until",
                    "pending_reason",
                    "next_update_at",
                    "review_due_at",
                    "provider_obligations"
                  ],
                  "properties": {
                    "receipt_id": {
                      "type": "string"
                    },
                    "cutoff_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "access_expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "credit_bytes_at_cut": {
                      "type": "string"
                    },
                    "confirmed_usage_bytes_at_cut": {
                      "type": "string"
                    },
                    "confirmed_usage_bytes_including_late_proof": {
                      "type": "string"
                    },
                    "pending_traffic_obligations": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "recovery_available_until": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "pending_reason": {
                      "type": "string"
                    },
                    "next_update_at": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "review_due_at": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "provider_obligations": {
                      "$ref": "#/components/schemas/ClosingProviderObligations"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON"
          },
          "404": {
            "description": "Receipt unavailable or proofs invalid"
          },
          "429": {
            "description": "Auth-flow rate limit; default 5/minute per source IP, action and gateway replica"
          },
          "503": {
            "description": "Accounting or receipt service unavailable"
          }
        }
      }
    },
    "/api/v1/closing-receipts/{receipt_id}/recovery/request": {
      "post": {
        "summary": "Request a fresh receipt recovery mailbox challenge",
        "description": "Requires the saved high-entropy recovery code. Valid retained kits enqueue a fresh 8-digit challenge to the retained encrypted verified address. Unknown, invalid or expired kits return the same opaque response with no mail. Challenges expire after 10 minutes or the earlier private-retention deadline; attempts are limited. Requests are rate-limited.",
        "security": [],
        "parameters": [
          {
            "name": "receipt_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "recovery_code"
                ],
                "properties": {
                  "recovery_code": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Generic accepted response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "challenge_id",
                    "message"
                  ],
                  "properties": {
                    "challenge_id": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON"
          },
          "429": {
            "description": "Auth-flow rate limit; default 5/minute per source IP, action and gateway replica"
          },
          "503": {
            "description": "Accounting or receipt service unavailable"
          }
        }
      }
    },
    "/api/v1/closing-receipts/{receipt_id}/recovery/verify": {
      "post": {
        "summary": "Replace a receipt link using the saved code and fresh mailbox proof",
        "description": "Saved code plus fresh mailbox proof atomically rotates the key. Recovery can replace an expired link only while private recovery material remains retained, including an explicitly reviewed finite extension. The NEW key expires at that retained deadline. Old keys never reactivate. Normal workspace access and private retention never extend through reissue. Default auth-flow limit: 5/minute/IP/action/pod.",
        "security": [],
        "parameters": [
          {
            "name": "receipt_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "recovery_code",
                  "challenge_id",
                  "code"
                ],
                "properties": {
                  "recovery_code": {
                    "type": "string"
                  },
                  "challenge_id": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New retrieval key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "receipt_id",
                    "retrieval_key",
                    "access_expires_at"
                  ],
                  "properties": {
                    "receipt_id": {
                      "type": "string"
                    },
                    "retrieval_key": {
                      "type": "string"
                    },
                    "access_expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON"
          },
          "404": {
            "description": "Receipt unavailable or proofs invalid"
          },
          "429": {
            "description": "Auth-flow rate limit; default 5/minute per source IP, action and gateway replica"
          },
          "503": {
            "description": "Accounting or receipt service unavailable"
          }
        }
      }
    },
    "/api/v1/workspaces/{id}/closing-receipt": {
      "post": {
        "summary": "Prepare a workspace closing receipt recovery kit",
        "description": "Current active owner with verified email only. Kit expires for preparation after one hour; replacement invalidates the previous kit. Save/download before final closure confirmation. Only hashes of high-entropy keys are stored; verified contact is scope-bound encrypted. No-store response. At most 10 preparations/hour per user/pod.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Private kit, returned once",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "receipt_id",
                    "retrieval_key",
                    "recovery_code",
                    "preparation_expires_at"
                  ],
                  "properties": {
                    "receipt_id": {
                      "type": "string"
                    },
                    "retrieval_key": {
                      "type": "string"
                    },
                    "recovery_code": {
                      "type": "string"
                    },
                    "preparation_expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "403": {
            "description": "Current owner required"
          },
          "404": {
            "description": "Workspace unavailable"
          },
          "409": {
            "description": "Verified contact required"
          },
          "429": {
            "description": "Preparation rate limit"
          },
          "503": {
            "description": "Receipts temporarily unavailable"
          }
        }
      }
    },
    "/api/v1/admin/closing-receipts/{receipt_id}/review": {
      "post": {
        "summary": "Review an unresolved closing traffic receipt and optional finite recovery extension",
        "description": "Platform-admin session only. Requires matching unresolved pinned bank evidence; isolation reason additionally requires a lost bank. Next update must be within 24h. A seven-day private recovery extension is allowed only in the final 24h of a still-valid retained window. Existing link expiry is NEVER changed. New link requires fresh recovery proof. Decision and normal outbox notification commit atomically. Does not settle accounting or restore spending/service access. Provider-only finality is not covered.",
        "parameters": [
          {
            "name": "receipt_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "operation_id",
                  "expected_sequence",
                  "pending_reason",
                  "extend_recovery",
                  "next_update_at"
                ],
                "properties": {
                  "operation_id": {
                    "type": "string",
                    "pattern": "^[a-zA-Z0-9_-]{8,96}$"
                  },
                  "expected_sequence": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "pending_reason": {
                    "type": "string",
                    "enum": [
                      "awaiting_bank_settlement",
                      "awaiting_isolation",
                      "awaiting_provider_resolution"
                    ]
                  },
                  "extend_recovery": {
                    "type": "boolean"
                  },
                  "next_update_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Original idempotent review decision",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "operation_id",
                    "review_sequence",
                    "recovery_available_until",
                    "link_expires_at",
                    "next_update_at",
                    "review_due_at"
                  ],
                  "properties": {
                    "operation_id": {
                      "type": "string"
                    },
                    "review_sequence": {
                      "type": "integer"
                    },
                    "recovery_available_until": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "link_expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "next_update_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "review_due_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid review"
          },
          "403": {
            "description": "Platform-admin browser session required"
          },
          "409": {
            "description": "Changed or expired case, no matching unresolved bank, or extension requested before final 24 hours of private retention"
          },
          "503": {
            "description": "Review unavailable; retry the same operation_id"
          }
        }
      }
    },
    "/api/v1/admin/closing-receipts": {
      "get": {
        "summary": "List retained closing receipt cases for review",
        "description": "Platform-admin browser session only. Bounded pagination; no contact or credential disclosure. An erased private kit does not erase its financial cutoff or immutable review history.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Retained closure cases including provider roots; private receipt material may already be expired or erased.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "cases",
                    "limit",
                    "offset"
                  ],
                  "properties": {
                    "cases": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "receipt_id",
                          "closure_id",
                          "link_expires_at",
                          "recovery_available_until",
                          "pending_reason",
                          "review_sequence",
                          "next_update_at",
                          "review_due_at",
                          "recovery_material_status",
                          "provider_obligations"
                        ],
                        "properties": {
                          "receipt_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "closure_id": {
                            "type": "string"
                          },
                          "link_expires_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "recovery_available_until": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "pending_reason": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "review_sequence": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "next_update_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "review_due_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "provider_obligations": {
                            "$ref": "#/components/schemas/ClosingProviderObligations"
                          },
                          "recovery_material_status": {
                            "type": "string",
                            "enum": [
                              "available",
                              "expired",
                              "erased"
                            ]
                          }
                        },
                        "additionalProperties": false
                      }
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "403": {
            "description": "Platform-admin session required"
          },
          "503": {
            "description": "Case observation unavailable"
          }
        }
      }
    },
    "/api/v1/admin/closing-receipts/{closure_id}/provider-state": {
      "get": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Read provider closure state",
        "description": "Read the retained closure financial frontier and blockers. Platform-admin session only. No receipt capability or ordinary workspace access is granted.",
        "parameters": [
          {
            "name": "closure_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "frontier_hash",
                    "checkout_intents",
                    "pending_subscription_cancellations",
                    "pending_refund_adjustments",
                    "pending_payment_events",
                    "resolution_recorded",
                    "decision_sequence",
                    "last_decision"
                  ],
                  "properties": {
                    "frontier_hash": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "checkout_intents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "pending_subscription_cancellations": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "pending_refund_adjustments": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "pending_payment_events": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "resolution_recorded": {
                      "type": "boolean",
                      "description": "A retained operator attestation matches the exact current financial facts. Later facts invalidate that match."
                    },
                    "decision_sequence": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "last_decision": {
                      "type": "string",
                      "enum": [
                        "",
                        "resolved",
                        "reopened"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not signed in"
          },
          "403": {
            "description": "Platform-admin session required"
          },
          "503": {
            "description": "Temporarily unavailable"
          },
          "404": {
            "description": "Closure not found"
          }
        }
      }
    },
    "/api/v1/admin/closing-receipts/{closure_id}/provider-resolution": {
      "post": {
        "tags": [
          "platform-admin"
        ],
        "summary": "Record verified provider closure resolution",
        "description": "Record an immutable trusted operator attestation supported by verified provider evidence for the exact submitted frontier. Pending subscription cancellation, internal refund adjustment or successful unprocessed payment/refund events prevent resolution. This endpoint does not call the provider, move money, discard inbox events, alter links or restore access. New facts automatically invalidate the current match. Retry the identical operation to acknowledge its historical decision; read state again to check current facts. Reopening records contrary evidence without rewriting the previous decision. Both actions require the current decision sequence; an old acknowledgement never reinstates withdrawn evidence.",
        "parameters": [
          {
            "name": "closure_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recorded decision; historical acknowledgement on exact retry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "operation_id",
                    "closure_id",
                    "actor_user_id",
                    "frontier_hash",
                    "evidence_reference",
                    "evidence_sha256",
                    "recorded_at",
                    "decision_sequence",
                    "decision"
                  ],
                  "properties": {
                    "operation_id": {
                      "type": "string",
                      "pattern": "^[a-zA-Z0-9_-]{8,96}$"
                    },
                    "frontier_hash": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "evidence_reference": {
                      "type": "string",
                      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_./:-]{7,159}$",
                      "description": "Reference to the original verified evidence in the protected provider case archive. No payer/contact or raw payload."
                    },
                    "evidence_sha256": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "closure_id": {
                      "type": "string"
                    },
                    "actor_user_id": {
                      "type": "string"
                    },
                    "recorded_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "decision_sequence": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "decision": {
                      "type": "string",
                      "enum": [
                        "resolved",
                        "reopened"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not signed in"
          },
          "403": {
            "description": "Platform-admin session required"
          },
          "503": {
            "description": "Temporarily unavailable"
          },
          "400": {
            "description": "Invalid evidence or confirmation"
          },
          "409": {
            "description": "Changed frontier, conflicting evidence or unsettled work"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "operation_id",
                  "frontier_hash",
                  "evidence_reference",
                  "evidence_sha256",
                  "confirmation",
                  "expected_sequence",
                  "decision"
                ],
                "properties": {
                  "operation_id": {
                    "type": "string",
                    "pattern": "^[a-zA-Z0-9_-]{8,96}$"
                  },
                  "frontier_hash": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  },
                  "evidence_reference": {
                    "type": "string",
                    "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_./:-]{7,159}$",
                    "description": "Reference to the original verified evidence in the protected provider case archive. No payer/contact or raw payload."
                  },
                  "evidence_sha256": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  },
                  "confirmation": {
                    "type": "string",
                    "enum": [
                      "provider-confirmed-no-payable-checkout-or-unsettled-payment",
                      "provider-evidence-requires-further-review"
                    ],
                    "description": "First value requires decision=resolved and verified terminal evidence. Second requires decision=reopened and records withdrawal or contradiction of the previous operator conclusion."
                  },
                  "expected_sequence": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Current decision_sequence returned by provider-state; concurrent decisions use compare-and-set."
                  },
                  "decision": {
                    "type": "string",
                    "enum": [
                      "resolved",
                      "reopened"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/closing-receipts/{receipt_id}/complete": {
      "post": {
        "summary": "Record the final closing receipt retrieval window for current financial facts",
        "description": "Platform-admin session only. Current pinned traffic must be terminal and provider review resolved. While private recovery remains valid, retains it for at least 30 days from completion. Existing link expiry never changes. One completion per distinct checked provider frontier; replay acknowledges the original operation without extending access or certifying later facts. Decision and outbox notice commit atomically. No financial mutations or workspace access.",
        "parameters": [
          {
            "name": "receipt_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "operation_id",
                  "expected_sequence"
                ],
                "properties": {
                  "operation_id": {
                    "type": "string",
                    "pattern": "^[a-zA-Z0-9_-]{8,96}$"
                  },
                  "expected_sequence": {
                    "type": "integer",
                    "minimum": 0
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Original completion decision",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "operation_id",
                    "review_sequence",
                    "completed_at",
                    "recovery_available_until",
                    "link_expires_at"
                  ],
                  "properties": {
                    "operation_id": {
                      "type": "string"
                    },
                    "review_sequence": {
                      "type": "integer"
                    },
                    "completed_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "recovery_available_until": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "link_expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "403": {
            "description": "Platform-admin session required"
          },
          "409": {
            "description": "Changed, already completed, pending or unavailable"
          },
          "503": {
            "description": "Receipt service temporarily unavailable"
          }
        }
      }
    },
    "/api/v1/tunnels/{id}/ingress-limit": {
      "put": {
        "tags": [
          "Tunnels"
        ],
        "summary": "Set optional connection limit (workspace owner only)",
        "description": "Zero disables live-tunnel storm protection. Router-owned refusal protection remains active. Existing admitted connections continue. Changes propagate via the route cache. Disabling bypasses prior customer-scoped blocks once applied.",
        "operationId": "putTunnelIngressLimit",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "connections_per_ip_per_minute"
                ],
                "properties": {
                  "connections_per_ip_per_minute": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 60000,
                    "default": 0,
                    "description": "Optional new-connection limit per source IP per hostname per minute. Zero disables customer storm protection. Routers count locally and propagate temporary blocks lazily; distributed bursts can exceed this number. Not an HTTP request, byte or spending cap."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connections_per_ip_per_minute": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 60000,
                      "default": 0,
                      "description": "Optional new-connection limit per source IP per hostname per minute. Zero disables customer storm protection. Routers count locally and propagate temporary blocks lazily; distributed bursts can exceed this number. Not an HTTP request, byte or spending cap."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid limit"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Workspace owner required"
          },
          "404": {
            "description": "No tunnel in this workspace"
          }
        }
      }
    },
    "/api/v1/admin/workspaces/{workspace_id}/tunnel-limit": {
      "parameters": [
        {
          "name": "workspace_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "platform-admin"
        ],
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Effective tunnel quota",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "workspace_id",
                    "tunnel_limit",
                    "tunnel_count",
                    "operator_tunnel_limit"
                  ],
                  "properties": {
                    "workspace_id": {
                      "type": "string"
                    },
                    "tunnel_limit": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 1000000,
                      "description": "Effective total allowance, the highest active grant; zero means none."
                    },
                    "tunnel_count": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "operator_tunnel_limit": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 1000000,
                      "description": "This operator grant only, zero if absent. Lowering it cannot remove a higher purchased or redeemed allowance."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Email-authenticated platform administrator with MFA required"
          },
          "404": {
            "description": "Active workspace not found"
          },
          "503": {
            "description": "Quota unavailable or update could not commit"
          }
        },
        "operationId": "getAdminWorkspaceTunnelLimit",
        "summary": "Read effective workspace tunnel quota"
      },
      "put": {
        "tags": [
          "platform-admin"
        ],
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Effective tunnel quota",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "workspace_id",
                    "tunnel_limit",
                    "tunnel_count",
                    "operator_tunnel_limit"
                  ],
                  "properties": {
                    "workspace_id": {
                      "type": "string"
                    },
                    "tunnel_limit": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 1000000,
                      "description": "Effective total allowance, the highest active grant; zero means none."
                    },
                    "tunnel_count": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "operator_tunnel_limit": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 1000000,
                      "description": "This operator grant only, zero if absent. Lowering it cannot remove a higher purchased or redeemed allowance."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Email-authenticated platform administrator with MFA required"
          },
          "404": {
            "description": "Active workspace not found"
          },
          "503": {
            "description": "Quota unavailable or update could not commit"
          },
          "400": {
            "description": "Invalid quota or missing reason"
          }
        },
        "operationId": "putAdminWorkspaceTunnelLimit",
        "summary": "Grant an explicit workspace tunnel quota",
        "description": "Updates the operator tunnel-capacity entitlement with a required reason. Highest active total allowance wins; a lower operator grant cannot cancel a higher code or bundle grant. Counts all workspace tunnels and gates new creation only. Does not grant traffic or service time, and does not remove existing tunnels.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tunnel_limit",
                  "reason"
                ],
                "properties": {
                  "tunnel_limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000000,
                    "description": "Total tunnel allowance granted to this workspace. The highest active grant wins; allowances do not add."
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
