{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenSteward Admin API",
    "version": "1.0.0",
    "description": "Operator-facing REST surface backing the admin UI. JWT-authenticated; every route emits an OpenAPI operation derived from its Zod validator."
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT minted by POST /api/auth/login. Send as `Authorization: Bearer <token>`."
      }
    },
    "schemas": {
      "LoginBody": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "minLength": 1,
            "description": "Login name of the admin user.",
            "example": "olivia.admin"
          },
          "password": {
            "type": "string",
            "minLength": 1,
            "description": "The user's password.",
            "example": "s3cr3t-password"
          }
        },
        "required": [
          "username",
          "password"
        ],
        "description": "Credentials for local username/password login."
      },
      "SetupBody": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "minLength": 1,
            "description": "Login name for the first admin user to create during initial setup.",
            "example": "olivia.admin"
          },
          "password": {
            "type": "string",
            "minLength": 1,
            "description": "Password for the first admin user.",
            "example": "s3cr3t-password"
          }
        },
        "required": [
          "username",
          "password"
        ],
        "description": "Credentials to bootstrap the first admin account on a fresh deployment."
      },
      "CreateUserBody": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Login name for the new admin user; unique within the deployment.",
            "example": "olivia.admin"
          },
          "password": {
            "type": "string",
            "minLength": 1,
            "description": "Initial password for the new user.",
            "example": "s3cr3t-password"
          },
          "role": {
            "description": "Access level to grant: `admin`, `operator`, or `viewer`.",
            "example": "admin",
            "$ref": "#/components/schemas/Role"
          },
          "email": {
            "description": "Optional email address. Set here it is owned by the console (`emailSource: manual`) and SSO never overwrites it.",
            "example": "olivia@northwind.example",
            "anyOf": [
              {
                "type": "string",
                "maxLength": 254,
                "format": "email",
                "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
                "description": "Email address (trimmed, at most 254 characters).",
                "example": "olivia@northwind.example"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "username",
          "password",
          "role"
        ],
        "description": "Request body to create an admin-console user."
      },
      "Role": {
        "type": "string",
        "enum": [
          "admin",
          "operator",
          "viewer"
        ]
      },
      "UpdateUserBody": {
        "type": "object",
        "properties": {
          "role": {
            "description": "New role for the account.",
            "example": "operator",
            "$ref": "#/components/schemas/Role"
          },
          "password": {
            "description": "New password for the account (policy-checked).",
            "example": "fresh-s3cr3t-password",
            "type": "string",
            "minLength": 1
          },
          "email": {
            "description": "New email address, or `null` to clear it. An address set here is owned by the console (`emailSource: manual`): SSO sign-ins and SCIM no longer overwrite it. Clearing it hands ownership back, so the next SSO sign-in may fill it from the identity provider.",
            "example": "olivia@northwind.example",
            "anyOf": [
              {
                "type": "string",
                "maxLength": 254,
                "format": "email",
                "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
                "description": "Email address (trimmed, at most 254 characters).",
                "example": "olivia@northwind.example"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "description": "Request body to update a console account."
      },
      "PutUserAvatarBody": {
        "type": "object",
        "properties": {
          "data": {
            "type": "string",
            "minLength": 1,
            "description": "The picture as base64, or as a `data:` URL. PNG, JPEG or WebP, at most 512 KB decoded. The type is read from the bytes; whatever a data URL declares is ignored, and SVG is refused.",
            "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
          }
        },
        "required": [
          "data"
        ],
        "description": "A profile picture to store for a console user."
      },
      "CreateRoleBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Display name; unique, case-insensitively.",
            "example": "Support lead"
          },
          "description": {
            "description": "What the role is for.",
            "example": "Reads data for the accounts they support.",
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          },
          "baseRole": {
            "description": "Built-in level a holder is treated as by role-gated routes. Cannot exceed your own.",
            "example": "operator",
            "$ref": "#/components/schemas/Role"
          },
          "permissions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Permission"
            },
            "description": "Permissions the role grants. Each must be one you hold yourself.",
            "example": [
              "connections:read",
              "data:read"
            ]
          }
        },
        "required": [
          "name",
          "baseRole",
          "permissions"
        ],
        "description": "Request body to create a custom role."
      },
      "Permission": {
        "type": "string",
        "enum": [
          "connections:read",
          "connections:manage",
          "data:read",
          "data:read_pii",
          "data:export",
          "dashboards:view",
          "dashboards:edit",
          "dashboards:share_all",
          "destinations:manage",
          "sql_access:manage",
          "roles:manage",
          "users:manage",
          "settings:manage"
        ],
        "description": "A fine-grained operator permission. See `GET /api/permissions` for the catalog.",
        "example": "data:read"
      },
      "UpdateRoleBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Display name; unique, case-insensitively.",
            "example": "Support lead"
          },
          "description": {
            "description": "What the role is for; `null` clears it.",
            "example": "Reads data for the accounts they support.",
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          },
          "baseRole": {
            "description": "New base role. Propagated to every holder.",
            "example": "operator",
            "$ref": "#/components/schemas/Role"
          },
          "permissions": {
            "description": "Replacement permission set.",
            "example": [
              "connections:read",
              "data:read",
              "data:export"
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Permission"
            }
          }
        },
        "description": "Request body to edit a custom role; omitted fields are unchanged."
      },
      "AssignUserRoleBody": {
        "type": "object",
        "properties": {
          "roleId": {
            "type": "string",
            "minLength": 1,
            "description": "Role to assign: `admin`, `operator`, `viewer`, or a custom role id.",
            "example": "operator"
          }
        },
        "required": [
          "roleId"
        ],
        "description": "Request body to assign a role to a console user."
      },
      "SetUserScopeBody": {
        "type": "object",
        "properties": {
          "mode": {
            "description": "`all` for every tenant, or `restricted` to `grants`.",
            "example": "restricted",
            "$ref": "#/components/schemas/ScopeMode"
          },
          "grants": {
            "description": "Tenants (and optionally verticals) granted when `mode` is `restricted`.",
            "example": [
              {
                "tenantId": "acme",
                "verticals": "*"
              }
            ],
            "maxItems": 500,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScopeGrant"
            }
          },
          "source": {
            "description": "`manual` (default) pins this scope; `idp` hands the user back to IdP scope rules, which overwrite it on the next SSO login.",
            "example": "manual",
            "type": "string",
            "enum": [
              "manual",
              "idp"
            ]
          }
        },
        "required": [
          "mode"
        ],
        "description": "Request body to set a console user's tenant scope."
      },
      "ScopeMode": {
        "type": "string",
        "enum": [
          "all",
          "restricted"
        ],
        "description": "`all` sees every tenant; `restricted` only the granted ones.",
        "example": "all"
      },
      "ScopeGrant": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Tenant the grant covers.",
            "example": "acme"
          },
          "verticals": {
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 64
                }
              }
            ],
            "description": "Verticals within the tenant: `*` for every vertical, or a list.",
            "example": "*"
          }
        },
        "required": [
          "tenantId",
          "verticals"
        ],
        "description": "Tenant (and optionally verticals) a scoped user may see."
      },
      "Vertical": {
        "type": "string",
        "enum": [
          "accounting",
          "crm",
          "ecommerce",
          "logistics",
          "payments",
          "docsign",
          "projects",
          "customer-support",
          "inventory"
        ],
        "description": "One of the nine verticals OpenSteward maps to a canonical API.",
        "example": "accounting"
      },
      "ConnectionSyncSchedule": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "default",
              "custom",
              "trigger_only",
              "once"
            ],
            "description": "`default` (the deployment interval), `custom` (every `intervalMinutes`), `trigger_only` (only when a sync is requested) or `once` (one sync when connected).",
            "example": "custom"
          },
          "intervalMinutes": {
            "description": "Minutes between syncs, 15–43200 (30 days). Required for `custom`; refused with any other mode.",
            "example": 120,
            "type": "integer",
            "minimum": 15,
            "maximum": 43200
          }
        },
        "required": [
          "mode"
        ],
        "additionalProperties": false,
        "description": "How often a connection's data is re-synced. `default` follows the deployment interval (runtime setting `data_store.sync.default_interval_minutes`); `custom` uses `intervalMinutes` (15–43200); `trigger_only` never syncs automatically, not even when connected; `once` syncs once when connected."
      },
      "PlatformEnableBody": {
        "type": "object",
        "properties": {
          "config": {
            "description": "Operator credentials/config to apply when enabling the platform; omit to enable without configuring.",
            "$ref": "#/components/schemas/PlatformConfig"
          }
        },
        "description": "Request body to enable a platform for a vertical, optionally supplying its config."
      },
      "PlatformConfig": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/PlatformConfigOauth2"
          },
          {
            "$ref": "#/components/schemas/PlatformConfigOauth2Cc"
          },
          {
            "$ref": "#/components/schemas/PlatformConfigApiKey"
          },
          {
            "$ref": "#/components/schemas/PlatformConfigBasic"
          },
          {
            "$ref": "#/components/schemas/PlatformConfigSession"
          }
        ],
        "description": "Operator-supplied platform configuration, keyed by `authType`.",
        "type": "object",
        "discriminator": {
          "propertyName": "authType",
          "mapping": {
            "oauth2": "#/components/schemas/PlatformConfigOauth2",
            "oauth2_cc": "#/components/schemas/PlatformConfigOauth2Cc",
            "api_key": "#/components/schemas/PlatformConfigApiKey",
            "basic": "#/components/schemas/PlatformConfigBasic",
            "session": "#/components/schemas/PlatformConfigSession"
          }
        }
      },
      "PlatformConfigOauth2": {
        "type": "object",
        "properties": {
          "authType": {
            "type": "string",
            "const": "oauth2",
            "description": "Discriminator selecting the standard authorization-code OAuth2 flow.",
            "example": "oauth2"
          },
          "clientId": {
            "type": "string",
            "minLength": 1,
            "description": "OAuth client ID issued by the platform.",
            "example": "opensteward"
          },
          "clientSecret": {
            "type": "string",
            "minLength": 1,
            "description": "OAuth client secret; write-only and never returned in responses.",
            "example": "s3cr3t-client-value"
          },
          "redirectUri": {
            "description": "Redirect/callback URI registered with the platform; defaults to the deployment callback if omitted.",
            "example": "https://app.acme.example/return",
            "type": "string",
            "format": "uri"
          },
          "scopes": {
            "description": "OAuth scopes to request; defaults to the adapter recommendation if omitted.",
            "example": [
              "accounting.transactions.read"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "authType",
          "clientId",
          "clientSecret"
        ]
      },
      "PlatformConfigOauth2Cc": {
        "type": "object",
        "properties": {
          "authType": {
            "type": "string",
            "const": "oauth2_cc",
            "description": "Discriminator selecting the OAuth2 client-credentials (machine-to-machine) flow.",
            "example": "oauth2_cc"
          },
          "clientId": {
            "type": "string",
            "minLength": 1,
            "description": "OAuth client ID issued by the platform.",
            "example": "opensteward"
          },
          "clientSecret": {
            "type": "string",
            "minLength": 1,
            "description": "OAuth client secret; write-only and never returned in responses.",
            "example": "s3cr3t-client-value"
          },
          "tokenUrl": {
            "type": "string",
            "format": "uri",
            "description": "Token endpoint to exchange client credentials for an access token.",
            "example": "https://idp.northwind.example/oauth/token"
          },
          "scopes": {
            "description": "OAuth scopes to request; defaults to the adapter recommendation if omitted.",
            "example": [
              "accounting.transactions.read"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "authType",
          "clientId",
          "clientSecret",
          "tokenUrl"
        ]
      },
      "PlatformConfigApiKey": {
        "type": "object",
        "properties": {
          "authType": {
            "type": "string",
            "const": "api_key",
            "description": "Discriminator selecting static API-key authentication.",
            "example": "api_key"
          },
          "apiKey": {
            "type": "string",
            "minLength": 1,
            "description": "API key used to authenticate to the platform; write-only and never returned.",
            "example": "osk_acme_8f3a"
          }
        },
        "required": [
          "authType",
          "apiKey"
        ]
      },
      "PlatformConfigBasic": {
        "type": "object",
        "properties": {
          "authType": {
            "type": "string",
            "const": "basic",
            "description": "Discriminator selecting HTTP Basic authentication.",
            "example": "basic"
          },
          "username": {
            "type": "string",
            "minLength": 1,
            "description": "Username for HTTP Basic auth to the platform.",
            "example": "olivia.admin"
          },
          "password": {
            "type": "string",
            "minLength": 1,
            "description": "Password for HTTP Basic auth; write-only and never returned.",
            "example": "s3cr3t-password"
          }
        },
        "required": [
          "authType",
          "username",
          "password"
        ]
      },
      "PlatformConfigSession": {
        "type": "object",
        "properties": {
          "authType": {
            "type": "string",
            "const": "session",
            "description": "Discriminator selecting cookie/session-based authentication.",
            "example": "session"
          },
          "config": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            },
            "description": "Free-form session parameters (e.g. cookies) required by the platform; write-only.",
            "example": {
              "cookie": "session=abc123"
            }
          }
        },
        "required": [
          "authType",
          "config"
        ]
      },
      "PlatformConfigSetBody": {
        "type": "object",
        "properties": {
          "config": {
            "description": "Operator credentials/config keys to merge into the platform's stored configuration.",
            "$ref": "#/components/schemas/PlatformConfigPatch"
          }
        },
        "required": [
          "config"
        ],
        "description": "Request body to merge keys into an operator platform configuration. Omitted keys keep their stored value; `null` clears a key."
      },
      "PlatformConfigPatch": {
        "type": "object",
        "properties": {
          "authType": {
            "description": "Accepted for symmetry with `PlatformConfig` and stored as-is; the effective auth type comes from adapter metadata, not from this body. Nullable like every other key, so a stored value can be cleared.",
            "example": "oauth2",
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "oauth2",
                  "oauth2_cc",
                  "api_key",
                  "basic",
                  "session"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "clientId": {
            "description": "OAuth client ID issued by the platform.",
            "example": "opensteward",
            "type": [
              "string",
              "null"
            ]
          },
          "clientSecret": {
            "description": "OAuth client secret; write-only and never returned. Omit to keep the stored secret.",
            "example": "s3cr3t-client-value",
            "type": [
              "string",
              "null"
            ]
          },
          "redirectUri": {
            "description": "Redirect/callback URI registered with the platform. Empty string or `null` clears it.",
            "example": "https://app.acme.example/return",
            "anyOf": [
              {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "uri"
                  },
                  {
                    "type": "string",
                    "const": ""
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "tokenUrl": {
            "description": "Token endpoint for the client-credentials flow.",
            "example": "https://idp.northwind.example/oauth/token",
            "anyOf": [
              {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "uri"
                  },
                  {
                    "type": "string",
                    "const": ""
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "scopes": {
            "description": "OAuth scopes to request; defaults to the adapter recommendation if omitted.",
            "example": [
              "accounting.transactions.read"
            ],
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "apiKey": {
            "description": "API key used to authenticate to the platform; write-only and never returned.",
            "example": "osk_acme_8f3a",
            "type": [
              "string",
              "null"
            ]
          },
          "username": {
            "description": "Username for HTTP Basic auth to the platform.",
            "example": "olivia.admin",
            "type": [
              "string",
              "null"
            ]
          },
          "password": {
            "description": "Password for HTTP Basic auth; write-only and never returned.",
            "example": "s3cr3t-password",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": {},
        "description": "Partial operator platform configuration. Submitted keys overwrite stored ones, omitted keys are preserved, and `null` clears a key. Adapter-specific keys beyond those named here are accepted and stored verbatim."
      },
      "CompanyInfoInput": {
        "type": "object",
        "properties": {
          "name": {
            "example": "Acme Industries",
            "type": [
              "string",
              "null"
            ]
          },
          "legalName": {
            "example": "Acme Industries, Inc.",
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "example": "Industrial supplies and equipment.",
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "example": "https://acme.example",
            "type": [
              "string",
              "null"
            ]
          },
          "logoDataUrl": {
            "example": "data:image/svg+xml;base64,PHN2Zz48L3N2Zz4=",
            "type": [
              "string",
              "null"
            ]
          },
          "primaryColor": {
            "example": "#1d4ed8",
            "type": [
              "string",
              "null"
            ]
          },
          "secondaryColor": {
            "example": "#0f172a",
            "type": [
              "string",
              "null"
            ]
          },
          "fontFamily": {
            "example": "Inter, sans-serif",
            "type": [
              "string",
              "null"
            ]
          },
          "fontDataUrl": {
            "example": "data:font/woff2;base64,d09GMgABAAAAAA==",
            "type": [
              "string",
              "null"
            ]
          },
          "fontUrl": {
            "example": "https://fonts.acme.example/inter.css",
            "type": [
              "string",
              "null"
            ]
          },
          "faviconDataUrl": {
            "example": "data:image/png;base64,iVBORw0KGgo=",
            "type": [
              "string",
              "null"
            ]
          },
          "hideAttribution": {
            "example": false,
            "type": [
              "boolean",
              "null"
            ]
          },
          "supportEmail": {
            "example": "jane.doe@acme.example",
            "type": [
              "string",
              "null"
            ]
          },
          "privacyPolicyUrl": {
            "example": "https://acme.example/privacy",
            "type": [
              "string",
              "null"
            ]
          },
          "termsOfServiceUrl": {
            "example": "https://acme.example/terms",
            "type": [
              "string",
              "null"
            ]
          },
          "addressLine1": {
            "example": "2500 Market Street",
            "type": [
              "string",
              "null"
            ]
          },
          "addressLine2": {
            "example": "Suite 300",
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "example": "San Francisco",
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "example": "CA",
            "type": [
              "string",
              "null"
            ]
          },
          "postalCode": {
            "example": "94114",
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "example": "US",
            "type": [
              "string",
              "null"
            ]
          },
          "baseUrl": {
            "example": "https://acme.example",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "description": "Editable company/branding fields accepted when updating company info."
      },
      "CreateEndUserBody": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "description": "Tenant (operator customer) the new end-user belongs to.",
            "example": "acme"
          },
          "email": {
            "type": "string",
            "format": "email",
            "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
            "description": "Primary email address of the end-user.",
            "example": "jane.doe@acme.example"
          },
          "displayName": {
            "description": "Friendly display name for the end-user.",
            "example": "Jane Doe",
            "type": "string"
          },
          "externalReference": {
            "description": "Operator's own identifier for this end-user.",
            "example": "acme-industries",
            "type": "string"
          },
          "pii": {
            "description": "Optional PII to attach to the new end-user.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/EndUserPii"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "tenantId",
          "email"
        ],
        "description": "Request body to create an end-user."
      },
      "EndUserPii": {
        "type": "object",
        "properties": {
          "firstName": {
            "description": "End-user's given name.",
            "example": "Jane",
            "type": "string"
          },
          "lastName": {
            "description": "End-user's family name.",
            "example": "Doe",
            "type": "string"
          },
          "personalIdNumber": {
            "description": "National/tax identifier; typically masked in responses.",
            "example": "***-**-1234",
            "type": "string"
          },
          "phone": {
            "description": "Contact phone number in E.164 or local format.",
            "example": "+1-415-555-0142",
            "type": "string"
          },
          "address": {
            "description": "End-user's postal address.",
            "$ref": "#/components/schemas/EndUserAddress"
          }
        },
        "description": "Personally identifiable information for an end-user; only returned when explicitly requested."
      },
      "EndUserAddress": {
        "type": "object",
        "properties": {
          "line1": {
            "description": "First line of the street address.",
            "example": "2500 Market Street",
            "type": "string"
          },
          "line2": {
            "description": "Second address line (suite, unit, etc.).",
            "example": "Suite 300",
            "type": "string"
          },
          "city": {
            "description": "City or locality.",
            "example": "San Francisco",
            "type": "string"
          },
          "region": {
            "description": "State, province, or region.",
            "example": "CA",
            "type": "string"
          },
          "postalCode": {
            "description": "Postal or ZIP code.",
            "example": "94114",
            "type": "string"
          },
          "country": {
            "description": "Country, typically an ISO 3166-1 alpha-2 code.",
            "example": "US",
            "type": "string"
          }
        },
        "description": "Postal address for an end-user, stored as part of their PII."
      },
      "UpdateEndUserBody": {
        "type": "object",
        "properties": {
          "displayName": {
            "description": "New display name; pass null to clear it.",
            "example": "Jane Doe",
            "type": [
              "string",
              "null"
            ]
          },
          "externalReference": {
            "description": "New external reference; pass null to clear it.",
            "example": "acme-industries",
            "type": [
              "string",
              "null"
            ]
          },
          "pii": {
            "description": "New PII to set; pass null to clear stored PII.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/EndUserPii"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "description": "Request body to update an end-user; omitted fields are left unchanged."
      },
      "ConnectSessionStatus": {
        "type": "string",
        "enum": [
          "active",
          "consumed",
          "expired"
        ]
      },
      "CreateConnectSessionBody": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "description": "Tenant (operator customer) the new session belongs to.",
            "example": "acme"
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Human-friendly label for the session.",
            "example": "Acme onboarding"
          },
          "endUserId": {
            "description": "Existing end-user to bind the session to; omit to create/resolve one from the customer fields.",
            "example": "cus_4Qm2Xa9Lr",
            "type": "string"
          },
          "customerEmail": {
            "description": "Email used to create or match the end-user when `endUserId` is not supplied.",
            "example": "jane.doe@acme.example",
            "type": "string",
            "format": "email",
            "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
          },
          "customerDisplayName": {
            "description": "Display name for the end-user when creating one from this request.",
            "example": "Jane Doe",
            "type": "string",
            "maxLength": 200
          },
          "allowedVerticals": {
            "description": "Restrict the session to these verticals; omit for all enabled verticals.",
            "example": [
              "accounting"
            ],
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "allowedPlatforms": {
            "description": "Restrict the session to these specific platforms.",
            "example": [
              {
                "vertical": "accounting",
                "slug": "xero"
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AllowedPlatform"
            }
          },
          "redirectUrl": {
            "description": "URL the customer returns to after connecting; omit to use the default.",
            "example": "https://app.acme.example/return",
            "type": "string",
            "format": "uri"
          },
          "expiresAt": {
            "description": "Expiry as an epoch-millis timestamp; omit to apply the default expiry window.",
            "example": 1769949600000,
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "oneTimeOnly": {
            "description": "When true, the generated link is consumed after a single successful connection.",
            "example": false,
            "type": "boolean"
          },
          "syncSchedule": {
            "description": "The sync schedule the connection made through this link starts with; omit for the deployment default. A one-time link always makes a `once` connection and refuses any other mode.",
            "$ref": "#/components/schemas/ConnectionSyncSchedule"
          },
          "scopes": {
            "description": "Explicit scopes to request when `scopePolicy` is `custom`; omit otherwise.",
            "example": [
              "accounting.transactions.read"
            ],
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "scopePolicy": {
            "description": "How scopes are decided, resolved per-platform at OAuth-start: 'read_only' (default for new links — read scopes, falling back to platform default), 'platform_default' (no override), or 'custom' (use `scopes`).",
            "example": "read_only",
            "type": "string",
            "enum": [
              "read_only",
              "platform_default",
              "custom"
            ]
          },
          "allowSelfRegister": {
            "description": "When true, the link allows a not-yet-known customer to self-identify during connect.",
            "example": false,
            "type": "boolean"
          }
        },
        "required": [
          "tenantId",
          "label"
        ],
        "additionalProperties": {},
        "description": "Request body to create a connect session / shareable connect link."
      },
      "AllowedPlatform": {
        "type": "object",
        "properties": {
          "vertical": {
            "type": "string",
            "minLength": 1,
            "description": "Vertical the allowed platform belongs to.",
            "example": "accounting"
          },
          "slug": {
            "type": "string",
            "minLength": 1,
            "description": "Slug of the platform the customer is allowed to connect.",
            "example": "xero"
          }
        },
        "required": [
          "vertical",
          "slug"
        ],
        "description": "A specific vertical+platform the customer is permitted to connect through a link."
      },
      "MintApiKeyBody": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "description": "Tenant (operator customer) the new key authenticates as.",
            "example": "acme"
          },
          "label": {
            "description": "Optional human-friendly label for the key.",
            "example": "Production key",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "description": "Permission scopes to grant the key; omit for the default scope set.",
            "example": [
              "customers:read",
              "connections:read"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "mode": {
            "description": "Which surface the key addresses: `live` keys work on `/v1/*`, `test` keys on the `/test/v1/*` sandbox. Omit for `live`.",
            "example": "live",
            "type": "string",
            "enum": [
              "live",
              "test"
            ]
          },
          "expiresAt": {
            "description": "Optional hard expiry, epoch ms. Past it the key no longer authenticates. Omit for a non-expiring key.",
            "example": 1782864000000,
            "anyOf": [
              {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "tenantId"
        ],
        "description": "Request body to mint a new tenant API key."
      },
      "RotateApiKeyBody": {
        "type": "object",
        "properties": {
          "overlapSeconds": {
            "description": "Grace window in seconds during which the old key still verifies. Defaults to 86400 (24h); 0 revokes it immediately.",
            "example": 3600,
            "type": "integer",
            "minimum": 0,
            "maximum": 2592000
          },
          "expiresAt": {
            "description": "Optional hard expiry for the REPLACEMENT key, epoch ms. Not inherited from the old key.",
            "example": null,
            "anyOf": [
              {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "description": "Request body to rotate a tenant API key."
      },
      "DiscoverOAuthIssuerBody": {
        "type": "object",
        "properties": {
          "issuer": {
            "type": "string",
            "minLength": 1,
            "description": "Issuer URL to read the discovery document from.",
            "example": "https://idp.corp.example/realms/main"
          }
        },
        "required": [
          "issuer"
        ],
        "description": "Read an issuer's OpenID discovery document without saving anything."
      },
      "CreateOAuthIssuerBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Operator-facing label.",
            "example": "Corp Keycloak"
          },
          "preset": {
            "description": "Vendor preset the claim names came from.",
            "example": "keycloak",
            "type": "string"
          },
          "issuer": {
            "type": "string",
            "minLength": 1,
            "description": "The exact `iss` value tokens carry.",
            "example": "https://idp.corp.example/realms/main"
          },
          "jwksUri": {
            "type": "string",
            "minLength": 1,
            "description": "Signing-key endpoint, normally taken from the discovery document.",
            "example": "https://idp.corp.example/realms/main/protocol/openid-connect/certs"
          },
          "audience": {
            "type": "string",
            "minLength": 1,
            "description": "The exact `aud` value tokens must carry. Required — a blank audience accepts every token the issuer ever minted.",
            "example": "https://opensteward.corp.internal"
          },
          "subjectClaim": {
            "type": "string",
            "minLength": 1,
            "description": "Which claim names the calling client.",
            "example": "azp"
          },
          "scopeClaim": {
            "type": "string",
            "minLength": 1,
            "description": "Which claim carries the scopes.",
            "example": "realm_access.roles"
          },
          "algorithms": {
            "description": "Accepted signature algorithms. Asymmetric only.",
            "example": [
              "RS256"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "authorityMode": {
            "description": "Where tenant and scopes come from.",
            "example": "registry",
            "type": "string",
            "enum": [
              "registry",
              "intersect",
              "external"
            ]
          },
          "tenantClaim": {
            "description": "External mode only: which claim names the tenant.",
            "example": "https://opensteward/tenant",
            "type": [
              "string",
              "null"
            ]
          },
          "allowedTenants": {
            "description": "External mode only: tenants this issuer may assert. Empty admits nobody.",
            "example": [
              "acme"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "maxTokenLifetimeS": {
            "description": "External mode only: reject tokens living longer than this.",
            "example": 3600,
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "enabled": {
            "description": "Whether tokens from it are accepted.",
            "example": true,
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "issuer",
          "jwksUri",
          "audience",
          "subjectClaim",
          "scopeClaim"
        ],
        "description": "Register an identity provider whose tokens the developer API accepts."
      },
      "UpdateOAuthIssuerBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Operator-facing label.",
            "example": "Corp Keycloak"
          },
          "preset": {
            "description": "Vendor preset the claim names came from.",
            "example": "keycloak",
            "type": "string"
          },
          "issuer": {
            "type": "string",
            "minLength": 1,
            "description": "The exact `iss` value tokens carry.",
            "example": "https://idp.corp.example/realms/main"
          },
          "jwksUri": {
            "type": "string",
            "minLength": 1,
            "description": "Signing-key endpoint, normally taken from the discovery document.",
            "example": "https://idp.corp.example/realms/main/protocol/openid-connect/certs"
          },
          "audience": {
            "type": "string",
            "minLength": 1,
            "description": "The exact `aud` value tokens must carry. Required — a blank audience accepts every token the issuer ever minted.",
            "example": "https://opensteward.corp.internal"
          },
          "subjectClaim": {
            "type": "string",
            "minLength": 1,
            "description": "Which claim names the calling client.",
            "example": "azp"
          },
          "scopeClaim": {
            "type": "string",
            "minLength": 1,
            "description": "Which claim carries the scopes.",
            "example": "realm_access.roles"
          },
          "algorithms": {
            "description": "Accepted signature algorithms. Asymmetric only.",
            "example": [
              "RS256"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "authorityMode": {
            "description": "Where tenant and scopes come from.",
            "example": "registry",
            "type": "string",
            "enum": [
              "registry",
              "intersect",
              "external"
            ]
          },
          "tenantClaim": {
            "description": "External mode only: which claim names the tenant.",
            "example": "https://opensteward/tenant",
            "type": [
              "string",
              "null"
            ]
          },
          "allowedTenants": {
            "description": "External mode only: tenants this issuer may assert. Empty admits nobody.",
            "example": [
              "acme"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "maxTokenLifetimeS": {
            "description": "External mode only: reject tokens living longer than this.",
            "example": 3600,
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "enabled": {
            "description": "Whether tokens from it are accepted.",
            "example": true,
            "type": "boolean"
          }
        },
        "description": "Fields to change. The merged row is validated, not the patch — switching to external authority without naming a tenant claim is refused here rather than failing open at request time."
      },
      "CreateOAuthClientBody": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string",
            "minLength": 1,
            "description": "Value of the issuer's subject claim identifying this client.",
            "example": "billing-service"
          },
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "description": "Tenant it authenticates as.",
            "example": "acme"
          },
          "label": {
            "description": "Human-friendly label.",
            "example": "Billing service",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Scopes to grant — the same vocabulary API keys use.",
            "example": [
              "customers:read"
            ]
          }
        },
        "required": [
          "subject",
          "tenantId",
          "scopes"
        ],
        "description": "Register a service account against an issuer."
      },
      "CreateOAuthScopeRuleBody": {
        "type": "object",
        "properties": {
          "claimValue": {
            "type": "string",
            "minLength": 1,
            "description": "A value as it appears in the token's scope claim.",
            "example": "read:ledger"
          },
          "grantedScope": {
            "type": "string",
            "minLength": 1,
            "description": "The OpenSteward scope it grants.",
            "example": "vertical:accounting"
          },
          "priority": {
            "description": "Evaluation order, ascending.",
            "example": 0,
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "claimValue",
          "grantedScope"
        ],
        "description": "Map one of the IdP's scope values onto an OpenSteward scope."
      },
      "MintEndUserTokenBody": {
        "type": "object",
        "properties": {
          "endUserId": {
            "type": "string",
            "minLength": 1,
            "description": "End-user the token will authenticate as (prefix `cus_`).",
            "example": "cus_4Qm2Xa9Lr"
          },
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "description": "Tenant the end-user belongs to.",
            "example": "acme"
          },
          "label": {
            "description": "Optional human-friendly label for the token.",
            "example": "Production key",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "description": "Permission scopes to grant the token; omit for the default scope set.",
            "example": [
              "customers:read",
              "connections:read"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "endUserId",
          "tenantId"
        ],
        "description": "Request body to mint an API token scoped to a single end-user."
      },
      "CreateWebhookSubscriptionBody": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "description": "Tenant (operator customer) that will own the subscription.",
            "example": "acme"
          },
          "url": {
            "type": "string",
            "minLength": 1,
            "description": "HTTPS endpoint that will receive event deliveries.",
            "example": "https://hooks.acme.example/opensteward"
          },
          "label": {
            "description": "Optional human-friendly name for the subscription, shown and searched in the admin list.",
            "example": "Billing service",
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ]
          },
          "events": {
            "description": "Event types to subscribe to; omit to subscribe to all events.",
            "example": [
              "customer.created"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "format": {
            "description": "Payload shape for this endpoint. Defaults to `opensteward`, the signed event envelope. Use `slack` for a Slack incoming webhook, `teams` for a Teams Workflows URL, `flat` for tools that only map top-level fields.",
            "example": "slack",
            "type": "string",
            "enum": [
              "opensteward",
              "slack",
              "teams",
              "flat"
            ]
          },
          "headers": {
            "description": "Custom headers sent with every delivery, for receivers that authenticate by header. Stored encrypted and never returned. Reserved names (`x-oi-*`, `host`, `content-*`, hop-by-hop) are rejected.",
            "example": {
              "X-Api-Key": "k-123"
            },
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "tenantId",
          "url"
        ],
        "description": "Request body to create a webhook subscription. The signing secret is returned once in the response."
      },
      "UpdateWebhookSubscriptionBody": {
        "type": "object",
        "properties": {
          "format": {
            "description": "New payload shape for this endpoint.",
            "example": "slack",
            "type": "string",
            "enum": [
              "opensteward",
              "slack",
              "teams",
              "flat"
            ]
          },
          "headers": {
            "description": "Replaces the custom headers wholesale; an empty object or null clears them. Values are never returned.",
            "example": {
              "X-Api-Key": "k-456"
            },
            "anyOf": [
              {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "label": {
            "description": "New human-friendly name for the subscription. Null or a blank string clears it; omit the field to leave it unchanged.",
            "example": "Billing service",
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "description": "Request body to change a webhook subscription's label or delivery settings. The URL and event list are immutable."
      },
      "SyncJobStatus": {
        "type": "string",
        "enum": [
          "pending",
          "running",
          "completed",
          "failed"
        ]
      },
      "CreateSyncJobBody": {
        "type": "object",
        "properties": {
          "connection_id": {
            "type": "string",
            "minLength": 1,
            "description": "Connection to sync (prefix `conn_`).",
            "example": "conn_1042"
          },
          "callback_url": {
            "description": "Optional URL notified when the sync job completes.",
            "example": "https://app.acme.example/sync-callback",
            "type": "string"
          }
        },
        "required": [
          "connection_id"
        ],
        "description": "Request body to enqueue a data-sync job for a connection."
      },
      "CreateScopeGroupBody": {
        "type": "object",
        "properties": {
          "vertical": {
            "type": "string",
            "minLength": 1,
            "description": "Vertical the scope group applies to.",
            "example": "accounting"
          },
          "platform": {
            "type": "string",
            "minLength": 1,
            "description": "Platform slug the scope group applies to.",
            "example": "xero"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Human-friendly label for the scope group.",
            "example": "Accounting read"
          },
          "scopes": {
            "description": "Scopes included in the group.",
            "$ref": "#/components/schemas/ScopeInput"
          }
        },
        "required": [
          "vertical",
          "platform",
          "name",
          "scopes"
        ],
        "description": "Request body to create a named scope group."
      },
      "ScopeInput": {
        "anyOf": [
          {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A single platform scope/permission.",
              "example": "accounting.transactions.read"
            },
            "description": "Scopes as an explicit array of strings.",
            "example": [
              "accounting.transactions.read"
            ]
          },
          {
            "type": "string",
            "description": "Scopes as a single whitespace/comma-separated string; normalised to an array server-side.",
            "example": "accounting.transactions.read"
          }
        ],
        "description": "Scopes accepted either as a string array or a delimited string; normalised to a deduped array on save."
      },
      "UpdateScopeGroupBody": {
        "type": "object",
        "properties": {
          "name": {
            "description": "New label for the scope group.",
            "example": "Accounting read",
            "type": "string",
            "minLength": 1
          },
          "scopes": {
            "description": "Replacement set of scopes for the group.",
            "$ref": "#/components/schemas/ScopeInput"
          }
        },
        "description": "Request body to update a scope group; omitted fields are left unchanged."
      },
      "CreateConnectLinkTemplateBody": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "description": "Tenant (operator customer) that will own the template.",
            "example": "acme"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Human-friendly name for the template.",
            "example": "Acme onboarding"
          },
          "description": {
            "description": "Optional longer description of the template.",
            "example": "Onboarding link for Acme Industries.",
            "type": [
              "string",
              "null"
            ]
          },
          "linkMode": {
            "description": "How the customer chooses what to connect: `pinned`, `customer-picks-adapter`, or `self-register`.",
            "example": "pinned",
            "$ref": "#/components/schemas/ConnectLinkMode"
          },
          "allowedVerticals": {
            "description": "Verticals the customer may connect; required/used depending on `linkMode`.",
            "example": [
              "accounting"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "allowedPlatforms": {
            "description": "Specific platforms the customer may connect; required for `pinned` mode.",
            "example": [
              {
                "vertical": "accounting",
                "slug": "xero"
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AllowedPlatform"
            }
          },
          "scopeGroupId": {
            "description": "Scope group whose scopes generated links request; omit for defaults.",
            "example": 7,
            "type": [
              "number",
              "null"
            ]
          },
          "expiryDays": {
            "description": "Days a generated link stays valid before expiring; omit for the default.",
            "example": 7,
            "type": "number"
          },
          "oneTimeOnly": {
            "description": "When true, generated links are consumed after a single successful connection.",
            "example": false,
            "type": "boolean"
          },
          "redirectUrl": {
            "description": "URL the customer returns to after connecting; omit for the default.",
            "example": "https://app.acme.example/return",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "tenantId",
          "name",
          "linkMode"
        ],
        "description": "Request body to create a connect-link template."
      },
      "ConnectLinkMode": {
        "type": "string",
        "enum": [
          "pinned",
          "customer-picks-adapter",
          "self-register"
        ]
      },
      "UpdateConnectLinkTemplateBody": {
        "type": "object",
        "properties": {
          "name": {
            "description": "New name for the template.",
            "example": "Acme onboarding",
            "type": "string"
          },
          "description": {
            "description": "New description; pass null to clear it.",
            "example": "Onboarding link for Acme Industries.",
            "type": [
              "string",
              "null"
            ]
          },
          "linkMode": {
            "description": "New link mode controlling what the customer can connect.",
            "example": "pinned",
            "$ref": "#/components/schemas/ConnectLinkMode"
          },
          "allowedVerticals": {
            "description": "New set of verticals the customer may connect.",
            "example": [
              "accounting"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "allowedPlatforms": {
            "description": "New set of platforms the customer may connect.",
            "example": [
              {
                "vertical": "accounting",
                "slug": "xero"
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AllowedPlatform"
            }
          },
          "scopeGroupId": {
            "description": "New scope group; pass null to clear it.",
            "example": 7,
            "type": [
              "number",
              "null"
            ]
          },
          "expiryDays": {
            "description": "New link validity window in days.",
            "example": 7,
            "type": "number"
          },
          "oneTimeOnly": {
            "description": "Whether generated links should be single-use.",
            "example": false,
            "type": "boolean"
          },
          "redirectUrl": {
            "description": "New post-connect redirect URL; pass null to clear it.",
            "example": "https://app.acme.example/return",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "description": "Request body to update a connect-link template; omitted fields are left unchanged."
      },
      "CreateTenantBody": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Optional stable tenant id (slug); generated from the name if omitted.",
            "example": "acme",
            "type": "string",
            "minLength": 1
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Human-friendly tenant name.",
            "example": "Acme Industries"
          }
        },
        "required": [
          "name"
        ],
        "description": "Request body to register a new tenant."
      },
      "UpdateTenantBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "New human-friendly tenant name.",
            "example": "Acme Industries"
          }
        },
        "required": [
          "name"
        ],
        "description": "Request body to rename a tenant."
      },
      "AddTenantDomainBody": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "minLength": 1,
            "description": "Custom domain to map (lower-cased, no scheme).",
            "example": "dept-a.acme.com"
          },
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "description": "Tenant the domain should resolve to.",
            "example": "acme"
          }
        },
        "required": [
          "domain",
          "tenantId"
        ],
        "description": "Request body to attach a custom domain to a tenant."
      },
      "DismissDashboardTasksBody": {
        "type": "object",
        "properties": {
          "items": {
            "minItems": 1,
            "maxItems": 50,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DashboardDismissItem"
            },
            "description": "Tasks to clear (1..50). Re-clearing a key replaces its fingerprint.",
            "example": [
              {
                "key": "conn:expired:conn_1042",
                "fingerprint": "2026-09-01T00:00:00.000Z"
              }
            ]
          }
        },
        "required": [
          "items"
        ],
        "description": "Request body to clear dashboard tasks."
      },
      "DashboardDismissItem": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^(conn:expired|platform:creds|sync:failed|refresh:failing|wizard):[A-Za-z0-9_.:/-]{1,300}$",
            "description": "Task key: `conn:expired:<connectionId>`, `platform:creds:<vertical>/<platform>`, `sync:failed:<jobId>`, `refresh:failing:<connectionId>` or `wizard:<step>`. A `vertical:down:*` row is not clearable and is refused.",
            "example": "conn:expired:conn_1042"
          },
          "fingerprint": {
            "type": "string",
            "maxLength": 300,
            "description": "Fingerprint of the condition being cleared, as derived by the dashboard (ISO 8601 for timestamps, empty when the key alone identifies it). The task re-surfaces when the live fingerprint differs.",
            "example": "2026-09-01T00:00:00.000Z"
          }
        },
        "required": [
          "key",
          "fingerprint"
        ],
        "description": "One dashboard task to clear."
      },
      "UpdateRuntimeSettingBody": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/UpdateRuntimeSettingBodyNumber"
          },
          {
            "$ref": "#/components/schemas/UpdateRuntimeSettingBodyBoolean"
          },
          {
            "$ref": "#/components/schemas/UpdateRuntimeSettingBodyString"
          },
          {
            "$ref": "#/components/schemas/UpdateRuntimeSettingBodyJson"
          },
          {
            "$ref": "#/components/schemas/UpdateRuntimeSettingBodyLogosSource"
          }
        ],
        "description": "PATCH body for /api/runtime-settings/{key}. Discriminated on `key`, one branch per value shape, so the `value` field is typed as number / boolean / string / a closed vocabulary / unknown for JSON.",
        "type": "object",
        "discriminator": {
          "propertyName": "key",
          "mapping": {
            "rate_limit.api_key.per_minute": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "rate_limit.api_key.window_ms": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "rate_limit.mcp_tenant.per_minute": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "rate_limit.mcp_end_user.per_minute": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "rate_limit.connect_link.per_minute": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "connect_link.default_expiry_hours": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "data_store.sync.default_interval_minutes": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "webhooks.delivery_retention_days": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "webhooks.inbound_event_retention_days": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "audit_log.retention_days": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "logos.fetch_delay_ms": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "logos.job_retention_days": "#/components/schemas/UpdateRuntimeSettingBodyNumber",
            "features.mcp_enabled": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "features.end_user_mode_enabled": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "features.test_mode_enabled": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "connect_link.one_time_default": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "auth.local_login_enabled": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "auth.dev_api_keys_enabled": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "auth.dev_oauth_enabled": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "auth.sandbox_self_serve_enabled": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "data_store.raw_payload.payments": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "data_store.raw_payload.accounting": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "data_store.sync.scheduler_enabled": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "data_access.mask_financial": "#/components/schemas/UpdateRuntimeSettingBodyBoolean",
            "auth.break_glass_user_id": "#/components/schemas/UpdateRuntimeSettingBodyString",
            "logos.brandfetch_client_id": "#/components/schemas/UpdateRuntimeSettingBodyString",
            "logos.fetch_referer": "#/components/schemas/UpdateRuntimeSettingBodyString",
            "openapi.servers.scheme": "#/components/schemas/UpdateRuntimeSettingBodyJson",
            "openapi.servers.host": "#/components/schemas/UpdateRuntimeSettingBodyJson",
            "openapi.servers.port": "#/components/schemas/UpdateRuntimeSettingBodyJson",
            "openapi.servers.version": "#/components/schemas/UpdateRuntimeSettingBodyJson",
            "logos.source": "#/components/schemas/UpdateRuntimeSettingBodyLogosSource"
          }
        }
      },
      "UpdateRuntimeSettingBodyNumber": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "rate_limit.api_key.per_minute",
              "rate_limit.api_key.window_ms",
              "rate_limit.mcp_tenant.per_minute",
              "rate_limit.mcp_end_user.per_minute",
              "rate_limit.connect_link.per_minute",
              "connect_link.default_expiry_hours",
              "data_store.sync.default_interval_minutes",
              "webhooks.delivery_retention_days",
              "webhooks.inbound_event_retention_days",
              "audit_log.retention_days",
              "logos.fetch_delay_ms",
              "logos.job_retention_days"
            ],
            "description": "Setting key being updated; must equal the `{key}` path parameter. The number-valued settings:\n- `rate_limit.api_key.per_minute` — Global default for tenant-scoped API keys on /v1/* routes (requests per window).\n- `rate_limit.api_key.window_ms` — Sliding-window length for the per-key rate limit (milliseconds).\n- `rate_limit.mcp_tenant.per_minute` — Tenant-mode MCP (mcp:read) budget. Defaults to parity with regular API keys — tenant-mode agents do legitimate cross-customer analytics.\n- `rate_limit.mcp_end_user.per_minute` — End-user MCP (mcp:read on eut_ tokens) budget. Keyed on end_user:<id> so two agent installs for the same customer share the budget. Tighter default — a single customer Q&A agent does not need 600/min.\n- `rate_limit.connect_link.per_minute` — Public /connect/{token} flow rate limit, keyed on client IP. Stops brute-force token guessing without throttling legitimate retries.\n- `connect_link.default_expiry_hours` — Default expiry for newly minted Connect Links when none is set on the form.\n- `data_store.sync.default_interval_minutes` — Minutes between syncs for connections on the default schedule. Each sync re-reads every resource from the platform, so a shorter interval costs platform API calls. Held to 15–43200 (30 days); 0 or less means the built-in 360.\n- `webhooks.delivery_retention_days` — Days to keep DELIVERED and DEAD outbound webhook deliveries. Their body column holds the full event JSON — customer emails and connection detail included — so unbounded retention is a data-protection liability, not just disk. Defaults to 30 days (delivery bodies are an operational log); set 0 to keep forever. Pending deliveries are never pruned; swept every ~6h by the delivery worker. Existing deployments keep whatever value they already have (seeding never overwrites).\n- `webhooks.inbound_event_retention_days` — Days to keep raw INBOUND platform webhook payloads (inbound_events) — order data and other customer PII arrives in these verbatim. 0 = keep forever (the default). Swept together with delivery retention.\n- `audit_log.retention_days` — Days of audit-log history to retain. 0 keeps everything forever. When positive, a daily background sweep deletes entries older than this many days (and records an audit.retention.prune entry when it removes any).\n- `logos.fetch_delay_ms` — Milliseconds between Brandfetch requests during a logo fetch. Brandfetch publishes 1,000 requests per 5 minutes per IP. 400ms holds the worst case (every logo found on the first attempt, which costs one request and one delay) at 150/min = 750 per 5 minutes. Lower it only if you have an agreement with Brandfetch.\n- `logos.job_retention_days` — Days of finished logo-fetch job history to keep. 0 keeps everything forever. Deleting the stored logos clears the history too, since those rows describe fetches whose output no longer exists; the audit log keeps the record either way.",
            "example": "rate_limit.api_key.per_minute"
          },
          "value": {
            "type": "number",
            "description": "New value for the setting named in `key` (number).",
            "example": 600
          }
        },
        "required": [
          "key",
          "value"
        ],
        "description": "Update body for the 12 number-valued runtime settings: `rate_limit.api_key.per_minute`, `rate_limit.api_key.window_ms`, `rate_limit.mcp_tenant.per_minute`, `rate_limit.mcp_end_user.per_minute`, `rate_limit.connect_link.per_minute`, `connect_link.default_expiry_hours`, `data_store.sync.default_interval_minutes`, `webhooks.delivery_retention_days`, `webhooks.inbound_event_retention_days`, `audit_log.retention_days`, `logos.fetch_delay_ms`, `logos.job_retention_days`."
      },
      "UpdateRuntimeSettingBodyBoolean": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "features.mcp_enabled",
              "features.end_user_mode_enabled",
              "features.test_mode_enabled",
              "connect_link.one_time_default",
              "auth.local_login_enabled",
              "auth.dev_api_keys_enabled",
              "auth.dev_oauth_enabled",
              "auth.sandbox_self_serve_enabled",
              "data_store.raw_payload.payments",
              "data_store.raw_payload.accounting",
              "data_store.sync.scheduler_enabled",
              "data_access.mask_financial"
            ],
            "description": "Setting key being updated; must equal the `{key}` path parameter. The boolean-valued settings:\n- `features.mcp_enabled` — When false, the integration-server refuses any token carrying mcp:read (403 MCP_DISABLED). Use for emergency disable without redeploying.\n- `features.end_user_mode_enabled` — When false, /v1/me/* routes are not mounted, so they 404. Read once at boot — unlike features.mcp_enabled, a change here needs a restart. End-user mode in MCP and the admin mint UX are inert until this is true.\n- `features.test_mode_enabled` — When false, the /test/v1/* sandbox refuses every request (503 TEST_MODE_DISABLED) within one settings poll. The live /v1/* surface is untouched either way, and test-mode API keys can still be minted and revoked — they simply have nothing to call.\n- `connect_link.one_time_default` — When true, new Connect Links default to one-time read-only mode. Templates and explicit form picks always win.\n- `auth.local_login_enabled` — When false, username/password login is rejected for everyone EXCEPT the pinned break-glass admin. Only disable once an SSO provider is verified working.\n- `auth.dev_api_keys_enabled` — When false, the integration-server refuses osk_ developer keys on /v1/* with 403 API_KEYS_DISABLED. Read per request, so a flip applies without a redeploy. Refused unless an OIDC issuer is enabled, reachable by somebody, and has actually verified a token — otherwise switching this off locks every developer out. X-Admin-Secret is never gated by it.\n- `auth.dev_oauth_enabled` — When true, /v1/* also accepts an OIDC bearer token from an issuer registered under OAuth clients. Defaults off because it means nothing until an issuer exists. Read per request, like features.mcp_enabled.\n- `auth.sandbox_self_serve_enabled` — When true, POST /test/v1/keys mints a sandbox API key with NO authentication — a developer evaluating this deployment gets a test key without asking an admin. Each key belongs to a fresh throwaway tenant, works only on the no-egress /test/v1/* sandbox, expires after 7 days, and minting is IP-rate-limited. Bulk-revoke via the mode=test filter on the API keys page. Read per request.\n- `data_store.raw_payload.payments` — When true, payments resources carry the full upstream payload under \\`raw\\`. Off by default: across the payments adapters that payload declares bank account numbers, IBANs and card numbers the canonical schema does not expose (it exposes last4). Card security codes are stripped either way — PCI DSS 3.3.1 permits no exception. Turning this off does NOT clean rows already written, and turning it on does NOT backfill rows already cached — clear the cache after either change.\n- `data_store.raw_payload.accounting` — When true, accounting resources carry the full upstream payload under \\`metadata\\`. Off by default: 17 accounting adapters declare IBAN, bank account or routing numbers there, and the canonical schema has no IBAN field. Turning this off does NOT clean rows already written, and turning it on does NOT backfill rows already cached — clear the cache after either change.\n- `data_store.sync.scheduler_enabled` — When false, nothing is synced on a schedule: default and custom schedules wait, and one-time connections without a first sync wait for it. Sync now, the API and the sync right after a Connect Link still run.\n- `data_access.mask_financial` — When true, fields classified \\`financial\\` (amounts, balances, prices) are masked in the admin data viewer and its exports, filters on them are refused, and dashboard metrics that sum them are withheld. Off by default: financial values are tagged but shown to anyone with \\`data:read\\`. Personal data is masked regardless of this setting unless the reader holds \\`data:read_pii\\`.",
            "example": "features.mcp_enabled"
          },
          "value": {
            "type": "boolean",
            "description": "New value for the setting named in `key` (boolean).",
            "example": true
          }
        },
        "required": [
          "key",
          "value"
        ],
        "description": "Update body for the 12 boolean-valued runtime settings: `features.mcp_enabled`, `features.end_user_mode_enabled`, `features.test_mode_enabled`, `connect_link.one_time_default`, `auth.local_login_enabled`, `auth.dev_api_keys_enabled`, `auth.dev_oauth_enabled`, `auth.sandbox_self_serve_enabled`, `data_store.raw_payload.payments`, `data_store.raw_payload.accounting`, `data_store.sync.scheduler_enabled`, `data_access.mask_financial`."
      },
      "UpdateRuntimeSettingBodyString": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "auth.break_glass_user_id",
              "logos.brandfetch_client_id",
              "logos.fetch_referer"
            ],
            "description": "Setting key being updated; must equal the `{key}` path parameter. The string-valued settings:\n- `auth.break_glass_user_id` — User id of the local admin that can always log in with a password, even when local login is disabled. Auto-pinned to the first-run admin when empty.\n- `logos.brandfetch_client_id` — Brandfetch client ID. Required for logos.source=cdn and to run a logo fetch. NOT a secret — Brandfetch designed it to be embedded in public <img> tags, so it is stored in plaintext. Free at https://brandfetch.com/developers.\n- `logos.fetch_referer` — Referer header sent on Brandfetch requests — they reject requests without one. Should match the origin registered for your Brandfetch app. Empty uses the project default.",
            "example": "auth.break_glass_user_id"
          },
          "value": {
            "type": "string",
            "description": "New value for the setting named in `key` (string).",
            "example": ""
          }
        },
        "required": [
          "key",
          "value"
        ],
        "description": "Update body for the 3 string-valued runtime settings: `auth.break_glass_user_id`, `logos.brandfetch_client_id`, `logos.fetch_referer`."
      },
      "UpdateRuntimeSettingBodyJson": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "openapi.servers.scheme",
              "openapi.servers.host",
              "openapi.servers.port",
              "openapi.servers.version"
            ],
            "description": "Setting key being updated; must equal the `{key}` path parameter. The json-valued settings:\n- `openapi.servers.scheme` — HTTP scheme for the Swagger UI \"Servers\" dropdown. Shape: { default: string, enum: string[] }. Edit when going live: {\"default\":\"https\",\"enum\":[\"https\",\"http\"]}.\n- `openapi.servers.host` — Hostname (no port) for the Servers dropdown. Add staging / prod hostnames to the enum, e.g. {\"default\":\"oi.acme.com\",\"enum\":[\"oi.acme.com\",\"oi-staging.acme.com\"]}.\n- `openapi.servers.port` — Port (as a string — OpenAPI server variables are strings). Use \"443\" for HTTPS deployments, \"80\" for plain HTTP, \"3010\" for local.\n- `openapi.servers.version` — URL-path API version segment (appended to {scheme}://{host}:{port}/ for /v1/{vertical}/* paths only). Add \"v2\" to the enum when a versioned route ships; /auth/* and /admin/* paths are unaffected.",
            "example": "openapi.servers.scheme"
          },
          "value": {
            "description": "New value for the setting named in `key` (json).",
            "example": {
              "default": "http",
              "enum": [
                "http",
                "https"
              ]
            }
          }
        },
        "required": [
          "key",
          "value"
        ],
        "description": "Update body for the 4 json-valued runtime settings: `openapi.servers.scheme`, `openapi.servers.host`, `openapi.servers.port`, `openapi.servers.version`."
      },
      "UpdateRuntimeSettingBodyLogosSource": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "logos.source"
            ],
            "description": "Setting key being updated; must equal the `{key}` path parameter. The enum-valued settings:\n- `logos.source` — Where platform logos come from. none = brand-tinted monogram tiles, no external requests, works air-gapped (the default). cdn = hotlink Brandfetch, the mode they sanction — needs logos.brandfetch_client_id. local = serve logos this deployment has fetched. An unknown value, or cdn with no client ID, falls back to none with a warning.",
            "example": "logos.source"
          },
          "value": {
            "type": "string",
            "enum": [
              "none",
              "cdn",
              "local"
            ],
            "description": "New value for the setting named in `key` (enum).",
            "example": "none"
          }
        },
        "required": [
          "key",
          "value"
        ],
        "description": "Update body for runtime setting `logos.source` (enum). Where platform logos come from. none = brand-tinted monogram tiles, no external requests, works air-gapped (the default). cdn = hotlink Brandfetch, the mode they sanction — needs logos.brandfetch_client_id. local = serve logos this deployment has fetched. An unknown value, or cdn with no client ID, falls back to none with a warning."
      },
      "CreateIdentityProviderBody": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/CreateOidcIdentityProviderBody"
          },
          {
            "$ref": "#/components/schemas/CreateSamlIdentityProviderBody"
          },
          {
            "$ref": "#/components/schemas/CreateLdapIdentityProviderBody"
          }
        ],
        "description": "Create an identity provider. Body is keyed by `protocol` — OIDC, SAML, and LDAP each pin the per-protocol config shape.",
        "type": "object",
        "discriminator": {
          "propertyName": "protocol",
          "mapping": {
            "oidc": "#/components/schemas/CreateOidcIdentityProviderBody",
            "saml": "#/components/schemas/CreateSamlIdentityProviderBody",
            "ldap": "#/components/schemas/CreateLdapIdentityProviderBody"
          }
        }
      },
      "CreateOidcIdentityProviderBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Human-friendly display name for the IdP.",
            "example": "Northwind SSO"
          },
          "slug": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "pattern": "^[a-z0-9-]+$",
            "description": "URL-safe identifier used in SSO routes; lowercase letters, digits, and hyphens only.",
            "example": "northwind"
          },
          "protocol": {
            "type": "string",
            "const": "oidc",
            "description": "Discriminator: creates an OpenID Connect provider.",
            "example": "oidc"
          },
          "enabled": {
            "description": "Whether the IdP is active immediately; defaults to enabled.",
            "example": true,
            "type": "boolean"
          },
          "config": {
            "description": "OIDC non-secret config; may be omitted now and filled in later.",
            "$ref": "#/components/schemas/OidcConfig"
          },
          "secret": {
            "$ref": "#/components/schemas/IdpSecretBundle"
          },
          "jitEnabled": {
            "description": "When true, users are just-in-time provisioned on first SSO login.",
            "example": true,
            "type": "boolean"
          },
          "defaultRole": {
            "description": "Role for JIT-provisioned users when no mapping rule matches.",
            "example": "viewer",
            "$ref": "#/components/schemas/Role"
          }
        },
        "required": [
          "name",
          "slug",
          "protocol"
        ],
        "description": "Request body to create an OIDC identity provider."
      },
      "OidcConfig": {
        "type": "object",
        "properties": {
          "issuer": {
            "type": "string",
            "format": "uri",
            "description": "OIDC issuer URL; the discovery document is fetched from `{issuer}/.well-known/openid-configuration`.",
            "example": "https://idp.northwind.example"
          },
          "clientId": {
            "type": "string",
            "minLength": 1,
            "description": "OAuth client ID registered with the OIDC provider.",
            "example": "opensteward"
          },
          "scopes": {
            "default": "openid profile email",
            "description": "Space-separated scopes to request; `openid` is always enforced server-side.",
            "example": "openid profile email",
            "type": "string"
          },
          "groupsClaim": {
            "default": "groups",
            "description": "Name of the claim carrying group membership, used by role-mapping rules.",
            "example": "groups",
            "type": "string"
          },
          "prompt": {
            "description": "Optional OIDC `prompt` value (e.g. `select_account`, `login`) forwarded on the authorization request.",
            "example": "select_account",
            "type": "string"
          },
          "acrValues": {
            "description": "Optional space-separated `acr_values` requesting a specific authentication context (e.g. an MFA level).",
            "example": "urn:mace:incommon:iap:silver",
            "type": "string"
          }
        },
        "required": [
          "issuer",
          "clientId"
        ]
      },
      "IdpSecretBundle": {
        "type": "object",
        "properties": {
          "clientSecret": {
            "description": "OIDC client secret; write-only.",
            "example": "s3cr3t-client-value",
            "type": "string"
          },
          "ldapBindPassword": {
            "description": "Password for the LDAP service-account bind DN; write-only.",
            "example": "s3cr3t-bind-password",
            "type": "string"
          },
          "spPrivateKey": {
            "description": "SAML service-provider private key (PEM) used to sign requests; write-only.",
            "example": "-----BEGIN PRIVATE KEY-----\n...",
            "type": "string"
          },
          "spCertificate": {
            "description": "SAML service-provider certificate (PEM); write-only.",
            "example": "-----BEGIN CERTIFICATE-----\n...",
            "type": "string"
          },
          "idpCert": {
            "description": "SAML IdP signing certificate (PEM) used to verify assertions; write-only.",
            "example": "-----BEGIN CERTIFICATE-----\n...",
            "type": "string"
          }
        },
        "description": "IdP secret bundle. Write-only — never returned over the API."
      },
      "CreateSamlIdentityProviderBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Human-friendly display name for the IdP.",
            "example": "Northwind SSO"
          },
          "slug": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "pattern": "^[a-z0-9-]+$",
            "description": "URL-safe identifier used in SSO routes; lowercase letters, digits, and hyphens only.",
            "example": "northwind"
          },
          "protocol": {
            "type": "string",
            "const": "saml",
            "description": "Discriminator: creates a SAML provider.",
            "example": "saml"
          },
          "enabled": {
            "description": "Whether the IdP is active immediately; defaults to enabled.",
            "example": true,
            "type": "boolean"
          },
          "config": {
            "description": "SAML non-secret config; may be omitted now and filled in later.",
            "$ref": "#/components/schemas/SamlConfig"
          },
          "secret": {
            "$ref": "#/components/schemas/IdpSecretBundle"
          },
          "jitEnabled": {
            "description": "When true, users are just-in-time provisioned on first SSO login.",
            "example": true,
            "type": "boolean"
          },
          "defaultRole": {
            "description": "Role for JIT-provisioned users when no mapping rule matches.",
            "example": "viewer",
            "$ref": "#/components/schemas/Role"
          }
        },
        "required": [
          "name",
          "slug",
          "protocol"
        ],
        "description": "Request body to create a SAML identity provider."
      },
      "SamlConfig": {
        "type": "object",
        "properties": {
          "entryPoint": {
            "type": "string",
            "format": "uri",
            "description": "IdP single sign-on URL where SAML AuthnRequests are sent.",
            "example": "https://idp.northwind.example/sso"
          },
          "idpIssuer": {
            "type": "string",
            "minLength": 1,
            "description": "The IdP's entityID/issuer, used to validate the issuer of incoming assertions.",
            "example": "https://idp.northwind.example/metadata"
          },
          "spEntityId": {
            "type": "string",
            "minLength": 1,
            "description": "Our service-provider entityID; the audience the IdP must assert in the response.",
            "example": "opensteward"
          },
          "groupsAttribute": {
            "default": "groups",
            "description": "SAML attribute carrying group membership, used by role-mapping rules.",
            "example": "groups",
            "type": "string"
          },
          "emailAttribute": {
            "default": "email",
            "description": "SAML attribute holding the user's email; falls back to nameID if absent.",
            "example": "email",
            "type": "string"
          },
          "pictureAttribute": {
            "description": "SAML attribute holding an https URL of the user's profile picture. When unset, `picture`, `photo`, `photoUrl` and `avatar` are tried. The picture is fetched by admin-api behind an SSRF guard; an uploaded picture is never replaced.",
            "example": "picture",
            "type": "string"
          }
        },
        "required": [
          "entryPoint",
          "idpIssuer",
          "spEntityId"
        ]
      },
      "CreateLdapIdentityProviderBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Human-friendly display name for the IdP.",
            "example": "Northwind SSO"
          },
          "slug": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "pattern": "^[a-z0-9-]+$",
            "description": "URL-safe identifier used in SSO routes; lowercase letters, digits, and hyphens only.",
            "example": "northwind"
          },
          "protocol": {
            "type": "string",
            "const": "ldap",
            "description": "Discriminator: creates an LDAP provider.",
            "example": "ldap"
          },
          "enabled": {
            "description": "Whether the IdP is active immediately; defaults to enabled.",
            "example": true,
            "type": "boolean"
          },
          "config": {
            "description": "LDAP non-secret config; may be omitted now and filled in later.",
            "$ref": "#/components/schemas/LdapConfig"
          },
          "secret": {
            "$ref": "#/components/schemas/IdpSecretBundle"
          },
          "jitEnabled": {
            "description": "When true, users are just-in-time provisioned on first successful login.",
            "example": true,
            "type": "boolean"
          },
          "defaultRole": {
            "description": "Role for JIT-provisioned users when no mapping rule matches.",
            "example": "viewer",
            "$ref": "#/components/schemas/Role"
          }
        },
        "required": [
          "name",
          "slug",
          "protocol"
        ],
        "description": "Request body to create an LDAP identity provider."
      },
      "LdapConfig": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "pattern": "^ldaps?:\\/\\/",
            "description": "LDAP server URL; use `ldaps://` for TLS (required in production).",
            "example": "ldaps://ldap.northwind.example"
          },
          "bindDn": {
            "type": "string",
            "minLength": 1,
            "description": "Distinguished name of the service account used to bind and search for users.",
            "example": "cn=svc,dc=northwind,dc=example"
          },
          "searchBase": {
            "type": "string",
            "minLength": 1,
            "description": "Base DN under which user entries are searched.",
            "example": "ou=people,dc=northwind,dc=example"
          },
          "searchFilter": {
            "default": "(uid={{username}})",
            "description": "LDAP search filter with a `{{username}}` placeholder substituted at login time.",
            "example": "(uid={{username}})",
            "type": "string"
          },
          "groupsAttribute": {
            "default": "memberOf",
            "description": "Attribute holding group membership (commonly `memberOf`), used by role-mapping rules.",
            "example": "memberOf",
            "type": "string"
          },
          "emailAttribute": {
            "default": "mail",
            "description": "Attribute holding the user's email address.",
            "example": "mail",
            "type": "string"
          },
          "displayNameAttribute": {
            "default": "cn",
            "description": "Attribute holding the user's display name.",
            "example": "cn",
            "type": "string"
          }
        },
        "required": [
          "url",
          "bindDn",
          "searchBase"
        ]
      },
      "UpdateIdentityProviderBody": {
        "type": "object",
        "properties": {
          "name": {
            "description": "New display name for the IdP.",
            "example": "Northwind SSO",
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "slug": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "pattern": "^[a-z0-9-]+$",
            "description": "URL-safe identifier used in SSO routes; lowercase letters, digits, and hyphens only.",
            "example": "northwind"
          },
          "enabled": {
            "description": "Enable or disable the IdP.",
            "example": true,
            "type": "boolean"
          },
          "config": {
            "description": "New non-secret config; shape must match the existing provider protocol (which is immutable).",
            "anyOf": [
              {
                "$ref": "#/components/schemas/OidcConfig"
              },
              {
                "$ref": "#/components/schemas/SamlConfig"
              },
              {
                "$ref": "#/components/schemas/LdapConfig"
              }
            ]
          },
          "secret": {
            "$ref": "#/components/schemas/IdpSecretBundle"
          },
          "jitEnabled": {
            "description": "Enable or disable just-in-time user provisioning on SSO login.",
            "example": true,
            "type": "boolean"
          },
          "defaultRole": {
            "description": "Role for JIT-provisioned users when no mapping rule matches.",
            "example": "viewer",
            "$ref": "#/components/schemas/Role"
          },
          "replaceUnreadableSecret": {
            "description": "Replace the stored secret bundle outright when it cannot be decrypted, accepting the loss of any secret not resent in this request. Without it such an update is refused with `409` so a recoverable STORE_SECRET mistake is not turned into permanent credential loss.",
            "example": false,
            "type": "boolean"
          }
        },
        "description": "Request body to update an identity provider; omitted fields are left unchanged. Protocol is immutable."
      },
      "CreateRoleMappingRuleBody": {
        "type": "object",
        "properties": {
          "priority": {
            "description": "Evaluation order; lower numbers are checked first and the first match wins.",
            "example": 10,
            "type": "integer",
            "minimum": 0,
            "maximum": 100000
          },
          "claimPath": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Path to the IdP claim/attribute to test, e.g. `groups`.",
            "example": "groups"
          },
          "matchType": {
            "description": "How `matchValue` is compared to the claim: `equals`, `contains`, or `regex`.",
            "example": "contains",
            "$ref": "#/components/schemas/RoleMatchType"
          },
          "matchValue": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "Value to compare against the claim using `matchType`.",
            "example": "opensteward-admins"
          },
          "role": {
            "description": "Built-in role granted when this rule matches. Required unless `roleId` is given.",
            "example": "admin",
            "$ref": "#/components/schemas/Role"
          },
          "roleId": {
            "description": "Role granted when this rule matches — a built-in id or a custom role id. Takes precedence over `role`.",
            "example": "operator",
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "claimPath",
          "matchType",
          "matchValue"
        ],
        "description": "Request body to create a role-mapping rule for an identity provider."
      },
      "RoleMatchType": {
        "type": "string",
        "enum": [
          "equals",
          "contains",
          "regex"
        ]
      },
      "CreateScopeMappingRuleBody": {
        "type": "object",
        "properties": {
          "priority": {
            "description": "Display order. Every matching scope rule applies; their tenants are unioned.",
            "example": 100,
            "type": "integer",
            "minimum": 0,
            "maximum": 100000
          },
          "claimPath": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Path to the IdP claim/attribute to test, e.g. `groups`.",
            "example": "groups"
          },
          "matchType": {
            "description": "How `matchValue` is compared to the claim: `equals`, `contains`, or `regex`.",
            "example": "equals",
            "$ref": "#/components/schemas/RoleMatchType"
          },
          "matchValue": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "Value to compare against the claim using `matchType`.",
            "example": "acme-support"
          },
          "tenantIds": {
            "minItems": 1,
            "maxItems": 500,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Tenants granted when the rule matches; `[\"*\"]` grants every tenant.",
            "example": [
              "acme"
            ]
          },
          "verticals": {
            "description": "Verticals within those tenants: `*` (default) for all, or a list.",
            "example": "*",
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 64
                }
              }
            ]
          }
        },
        "required": [
          "claimPath",
          "matchType",
          "matchValue",
          "tenantIds"
        ],
        "description": "Request body to create a scope-mapping rule for an identity provider."
      },
      "UpdateIdpDefaultScopeBody": {
        "type": "object",
        "properties": {
          "mode": {
            "description": "Scope when no scope rule matches: `all` tenants, or `restricted` to `tenantIds`.",
            "example": "restricted",
            "$ref": "#/components/schemas/ScopeMode"
          },
          "tenantIds": {
            "description": "Tenants granted by the default when `mode` is `restricted`; empty grants none.",
            "example": [
              "default"
            ],
            "maxItems": 500,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            }
          }
        },
        "required": [
          "mode"
        ],
        "description": "Request body to set an identity provider's default tenant scope."
      },
      "MintScimTokenBody": {
        "type": "object",
        "properties": {
          "label": {
            "description": "Optional human-friendly label for the SCIM token.",
            "example": "Production key",
            "type": "string"
          }
        },
        "description": "Request body to mint a SCIM provisioning token for an identity provider."
      },
      "SamlAcsBody": {
        "type": "object",
        "properties": {
          "SAMLResponse": {
            "description": "Base64-encoded SAML response POSTed by the IdP to the Assertion Consumer Service.",
            "example": "PHNhbWxwOlJlc3BvbnNlIC4uLj48L3NhbWxwOlJlc3BvbnNlPg==",
            "type": "string"
          },
          "RelayState": {
            "description": "Opaque relay state echoed back by the IdP, typically the post-login return path.",
            "example": "/dashboard",
            "type": "string"
          }
        },
        "description": "Form body the IdP POSTs to the SAML Assertion Consumer Service endpoint."
      },
      "LdapLoginBody": {
        "type": "object",
        "properties": {
          "username": {
            "description": "LDAP username to authenticate.",
            "example": "olivia.admin",
            "type": "string"
          },
          "password": {
            "description": "The user's LDAP password.",
            "example": "s3cr3t-password",
            "type": "string"
          }
        },
        "description": "Credentials submitted to authenticate against an LDAP identity provider."
      },
      "SsoHandoffBody": {
        "type": "object",
        "properties": {
          "code": {
            "description": "One-time handoff code exchanged for a session token after SSO completes.",
            "example": "sso_8f3a2b9c4d5e6f7a",
            "type": "string"
          }
        },
        "description": "Body carrying the one-time SSO handoff code to exchange for a bearer token."
      },
      "ScimResource": {
        "type": "object",
        "properties": {},
        "additionalProperties": {},
        "description": "A SCIM 2.0 resource (User or Group); an open object whose fields follow the SCIM schema for the endpoint."
      },
      "DataRevealBody": {
        "type": "object",
        "properties": {
          "reason": {
            "description": "Why you need the unmasked record; recorded in the audit log.",
            "example": "Support ticket #4821",
            "type": "string",
            "maxLength": 500
          }
        },
        "description": "Request body to reveal a stored record."
      },
      "MetricGranularityParam": {
        "type": "string",
        "enum": [
          "auto",
          "day",
          "week",
          "month"
        ],
        "description": "Time buckets for a series: `auto` is day up to 62 days, week up to 182, else month.",
        "example": "auto"
      },
      "CreateDashboardBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Name.",
            "example": "Weekly revenue"
          },
          "description": {
            "description": "What the dashboard is for.",
            "example": "Revenue across our shops.",
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          },
          "audience": {
            "$ref": "#/components/schemas/DashboardAudience"
          },
          "pinnedTenants": {
            "$ref": "#/components/schemas/DashboardPinnedTenants"
          },
          "widgets": {
            "maxItems": 24,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DashboardWidget"
            },
            "description": "Widgets in display order (at most 24).",
            "example": [
              {
                "metricId": "ecommerce.revenue_per_day",
                "chart": "bar",
                "width": 12
              }
            ]
          }
        },
        "required": [
          "name",
          "widgets"
        ],
        "description": "Request body to create a dashboard."
      },
      "DashboardAudience": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "private",
              "tenants",
              "everyone"
            ],
            "description": "`private` (only the owner), `tenants` (anyone whose tenant access includes any listed tenant) or `everyone` (every dashboards:view holder; setting it needs dashboards:share_all).",
            "example": "tenants"
          },
          "tenants": {
            "description": "For `tenants`: who it is shared with (1–500 tenant ids).",
            "example": [
              "acme"
            ],
            "maxItems": 500,
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 100,
              "pattern": "^[A-Za-z0-9._:-]+$",
              "description": "Tenant id.",
              "example": "acme"
            }
          }
        },
        "required": [
          "kind"
        ],
        "description": "Who can see a dashboard.",
        "example": {
          "kind": "tenants",
          "tenants": [
            "acme"
          ]
        }
      },
      "DashboardPinnedTenants": {
        "anyOf": [
          {
            "maxItems": 500,
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 100,
              "pattern": "^[A-Za-z0-9._:-]+$",
              "description": "Tenant id.",
              "example": "acme"
            }
          },
          {
            "type": "null"
          }
        ],
        "description": "Limit the data to these tenants (each viewer still sees only tenants in their own access). `null` = every tenant the viewer can see.",
        "example": [
          "acme"
        ]
      },
      "DashboardWidget": {
        "type": "object",
        "properties": {
          "metricId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "pattern": "^[a-z0-9][a-z0-9_.-]*$",
            "description": "Metric id from the catalog.",
            "example": "ecommerce.orders_per_day"
          },
          "title": {
            "description": "Heading shown on the widget; defaults to the metric title.",
            "example": "Orders (last 30 days)",
            "type": "string",
            "maxLength": 80
          },
          "chart": {
            "$ref": "#/components/schemas/DashboardChart"
          },
          "width": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12,
            "description": "Width in grid columns, out of 12.",
            "example": 6
          },
          "currency": {
            "description": "Pin the widget to one currency (ISO 4217). Absent or null follows the dashboard view's currency filter; with no filter every currency is drawn separately. Metrics without money or a currency field ignore it.",
            "example": "EUR",
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "granularity": {
            "$ref": "#/components/schemas/MetricGranularityParam"
          },
          "compare": {
            "description": "Also compute the prior equal-length period; number and gauge charts show the change. Only metrics marked `comparable` use it.",
            "example": true,
            "type": "boolean"
          }
        },
        "required": [
          "metricId",
          "chart",
          "width"
        ],
        "description": "One chart on a dashboard. `chart` must be one of its metric's `charts` (`400` otherwise)."
      },
      "DashboardChart": {
        "type": "string",
        "enum": [
          "number",
          "gauge",
          "table",
          "line",
          "area",
          "stacked_area",
          "bar",
          "hbar",
          "stacked_bar",
          "combo",
          "pareto",
          "pie",
          "donut",
          "rose",
          "treemap",
          "funnel",
          "radar",
          "histogram",
          "boxplot",
          "waterfall",
          "heatmap",
          "calendar"
        ],
        "description": "How a widget draws its metric.",
        "example": "line"
      },
      "UpdateDashboardBody": {
        "type": "object",
        "properties": {
          "name": {
            "description": "New name.",
            "example": "Weekly revenue",
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "description": {
            "description": "New description; `null` clears it.",
            "example": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          },
          "audience": {
            "$ref": "#/components/schemas/DashboardAudience"
          },
          "pinnedTenants": {
            "$ref": "#/components/schemas/DashboardPinnedTenants"
          },
          "widgets": {
            "description": "Replacement widget list (at most 24).",
            "example": [
              {
                "metricId": "ecommerce.orders_per_day",
                "chart": "line",
                "width": 6
              }
            ],
            "maxItems": 24,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DashboardWidget"
            }
          }
        },
        "description": "Request body to edit a dashboard."
      },
      "SupersetSharingBody": {
        "type": "object",
        "properties": {
          "audience": {
            "$ref": "#/components/schemas/DashboardAudience"
          },
          "pinnedTenants": {
            "$ref": "#/components/schemas/DashboardPinnedTenants"
          }
        },
        "description": "Who sees an embedded Superset dashboard."
      },
      "SupersetGuestTokenBody": {
        "type": "object",
        "properties": {
          "dashboardId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Registry id of the dashboard (`ssd_…`).",
            "example": "ssd_0123456789abcdef0123"
          }
        },
        "required": [
          "dashboardId"
        ],
        "description": "Request body to mint a guest token."
      },
      "CreateDestinationBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Display name.",
            "example": "Lake (prod)"
          },
          "type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40,
            "description": "Destination type.",
            "example": "s3"
          },
          "config": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {},
            "description": "The type's non-secret settings.",
            "example": {
              "bucket": "lake",
              "region": "eu-west-1"
            }
          },
          "secrets": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string",
              "maxLength": 20000
            },
            "description": "Write-only credentials, by field name (see the type catalog). Never returned or logged.",
            "example": {
              "accessKeyId": "AKIA…",
              "secretAccessKey": "…"
            }
          },
          "scope": {
            "$ref": "#/components/schemas/DestinationScope"
          },
          "includePii": {
            "description": "Export personal data unmasked. Needs `data:read_pii`; you are recorded as approver.",
            "example": false,
            "type": "boolean"
          },
          "intervalSec": {
            "description": "Seconds between runs, 60 to 604800 (default 3600).",
            "example": 3600,
            "type": "integer",
            "minimum": 60,
            "maximum": 604800
          },
          "enabled": {
            "description": "Run on schedule (default true).",
            "example": true,
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "type",
          "config",
          "scope"
        ],
        "description": "Request body to create a destination."
      },
      "DestinationScope": {
        "type": "object",
        "properties": {
          "tenants": {
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "maxItems": 1000,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                }
              }
            ],
            "description": "Owner tenants whose connections are exported, or `*` for every tenant (the only value that also exports connections with no owner tenant).",
            "example": [
              "acme"
            ]
          },
          "verticals": {
            "description": "Verticals exported, each with `*` or a list of resource types. Omit to export every vertical.",
            "example": {
              "crm": "*",
              "ecommerce": [
                "orders"
              ]
            },
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "string",
                  "const": "*"
                },
                {
                  "maxItems": 500,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  }
                }
              ]
            }
          },
          "maskFinancial": {
            "description": "Also mask financial fields (amounts, balances).",
            "example": false,
            "type": "boolean"
          }
        },
        "required": [
          "tenants"
        ],
        "description": "Which records a destination exports. Must lie inside your own tenant (and vertical) scope."
      },
      "UpdateDestinationBody": {
        "type": "object",
        "properties": {
          "name": {
            "description": "Display name.",
            "example": "Lake (prod)",
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "config": {
            "description": "The type's full non-secret settings (replaces the stored ones).",
            "example": {
              "bucket": "lake",
              "region": "eu-west-1"
            },
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "scope": {
            "$ref": "#/components/schemas/DestinationScope"
          },
          "includePii": {
            "description": "Export personal data unmasked. Turning it on needs `data:read_pii`.",
            "example": false,
            "type": "boolean"
          },
          "intervalSec": {
            "description": "Seconds between runs.",
            "example": 3600,
            "type": "integer",
            "minimum": 60,
            "maximum": 604800
          },
          "enabled": {
            "description": "Run on schedule.",
            "example": true,
            "type": "boolean"
          }
        },
        "description": "Request body to change a destination."
      },
      "DestinationCredentialsBody": {
        "type": "object",
        "properties": {
          "secrets": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string",
              "maxLength": 20000
            },
            "description": "Write-only credentials, by field name (see the type catalog). Never returned or logged.",
            "example": {
              "accessKeyId": "AKIA…",
              "secretAccessKey": "…"
            }
          }
        },
        "required": [
          "secrets"
        ],
        "description": "Replace a destination's credentials."
      },
      "DestinationBackfillBody": {
        "type": "object",
        "properties": {
          "vertical": {
            "description": "Only reset this vertical. Omit to re-export everything.",
            "example": "crm",
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "resourceType": {
            "description": "Only reset this resource type (needs `vertical`).",
            "example": "contacts",
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "run": {
            "description": "Start a run right away (default true).",
            "example": true,
            "type": "boolean"
          }
        },
        "description": "Request body to backfill a destination."
      },
      "CreateSqlPrincipalBody": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "A name for the login; becomes part of the username.",
            "example": "Metabase prod"
          },
          "pii": {
            "description": "Read the unmasked schema. Needs `data:read_pii`.",
            "example": false,
            "type": "boolean"
          },
          "scope": {
            "$ref": "#/components/schemas/CreateSqlPrincipalScope"
          },
          "expiresAt": {
            "description": "When the login stops working (ISO 8601); omit for never.",
            "example": "2027-01-01T00:00:00Z",
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
              },
              {
                "type": "null"
              }
            ]
          },
          "connectionLimit": {
            "description": "Concurrent sessions allowed (default 5).",
            "example": 5,
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          }
        },
        "required": [
          "label",
          "scope"
        ],
        "description": "Request body to create a SQL principal."
      },
      "CreateSqlPrincipalScope": {
        "type": "object",
        "properties": {
          "tenants": {
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "minItems": 1,
                "maxItems": 500,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                }
              }
            ],
            "description": "Owner tenants, or `*` for every tenant. Must lie inside your scope.",
            "example": [
              "acme"
            ]
          },
          "verticals": {
            "description": "Verticals; omit for all.",
            "example": [
              "crm"
            ],
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "minItems": 1,
                "maxItems": 20,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9-]*$"
                }
              }
            ]
          }
        },
        "required": [
          "tenants"
        ],
        "description": "What the new login may read."
      },
      "AuthTokenResponse": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "description": "Signed JWT bearer token; send as `Authorization: Bearer <token>` on subsequent requests.",
            "example": "eyJhbGciOiJIUzI1NiJ9.olivia"
          },
          "user": {
            "description": "Identity of the user the token was issued for.",
            "$ref": "#/components/schemas/MePayload"
          }
        },
        "required": [
          "token",
          "user"
        ],
        "additionalProperties": false,
        "description": "Successful authentication result: a bearer token plus the authenticated user."
      },
      "AccessScope": {
        "type": "object",
        "properties": {
          "mode": {
            "description": "`all` sees every tenant; `restricted` only the tenants in `grants`.",
            "example": "restricted",
            "$ref": "#/components/schemas/ScopeMode"
          },
          "grants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScopeGrantOutput"
            },
            "description": "Tenants granted. Empty when `mode` is `all`; a restricted user with none sees nothing.",
            "example": [
              {
                "tenantId": "acme",
                "verticals": "*"
              }
            ]
          }
        },
        "required": [
          "mode",
          "grants"
        ],
        "additionalProperties": false,
        "description": "Which tenants a console user may see."
      },
      "MePayload": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the authenticated user (prefix `usr_`).",
            "example": "usr_olivia"
          },
          "username": {
            "type": "string",
            "description": "Login name of the authenticated user.",
            "example": "olivia.admin"
          },
          "email": {
            "description": "Email address, or null when none is set. Set by an admin, or copied from the identity provider (OIDC `email`, SAML email attribute, SCIM `emails`).",
            "example": "olivia@northwind.example",
            "type": [
              "string",
              "null"
            ]
          },
          "avatarUrl": {
            "description": "Path of the profile picture on this API (`GET /api/users/{id}/avatar`), versioned with `?v=` so it changes whenever the picture does; null when the user has none.",
            "example": "/api/users/usr_olivia/avatar?v=9f86d081884c7d65",
            "type": [
              "string",
              "null"
            ]
          },
          "avatarVersion": {
            "description": "Short content hash of the profile picture, for cache-busting a proxied copy; null when the user has none.",
            "example": "9f86d081884c7d65",
            "type": [
              "string",
              "null"
            ]
          },
          "role": {
            "description": "Access level granted to the authenticated user.",
            "example": "admin",
            "$ref": "#/components/schemas/Role"
          },
          "roleId": {
            "description": "Effective role (custom role id, or the built-in id). Present on `GET /api/auth/me`; read from the database, so it reflects a change made since the token was issued.",
            "example": "operator",
            "type": "string"
          },
          "roleName": {
            "description": "Display name of the effective role. Present on `GET /api/auth/me`.",
            "example": "operator",
            "type": "string"
          },
          "permissions": {
            "description": "Effective permissions. Present on `GET /api/auth/me`.",
            "example": [
              "connections:read",
              "dashboards:view"
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Permission"
            }
          },
          "scope": {
            "description": "Tenant scope. Present on `GET /api/auth/me`.",
            "$ref": "#/components/schemas/AccessScope"
          }
        },
        "required": [
          "id",
          "username",
          "role"
        ],
        "additionalProperties": {},
        "description": "Identity of the currently authenticated user, derived from the JWT claims."
      },
      "ErrorBody": {
        "type": "object",
        "properties": {
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "properties": {
                  "code": {
                    "description": "Machine-readable error code, e.g. `invalid_request`.",
                    "example": "invalid_request",
                    "type": "string"
                  },
                  "message": {
                    "description": "Human-readable error message.",
                    "example": "Request validation failed.",
                    "type": "string"
                  }
                },
                "additionalProperties": {}
              }
            ],
            "description": "Error payload: either a terse string message or a structured object with `code`/`message`.",
            "example": "Not found"
          },
          "type": {
            "description": "Coarse error category: `validation`, `auth`, `not_found`, `conflict`, `rate_limit`, or `internal`.",
            "example": "not_found",
            "type": "string"
          },
          "requestId": {
            "description": "Correlation id for the request; also returned in the `X-Request-Id` response header. Quote it when reporting an issue.",
            "example": "req-8f3a2b9c",
            "type": "string"
          },
          "issues": {
            "description": "Validation issues (e.g. from Zod) when the error stems from request validation.",
            "example": [],
            "type": "array",
            "items": {}
          },
          "detail": {
            "description": "Additional detail, often forwarded from an upstream error.",
            "example": "Upstream returned 404.",
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": {},
        "description": "Standard error response. `error` is a string for terse messages or an object for structured codes; every response also carries an `X-Request-Id` header for correlation."
      },
      "HasUsersResponse": {
        "type": "object",
        "properties": {
          "hasUsers": {
            "type": "boolean",
            "description": "True once at least one admin user exists.",
            "example": false
          }
        },
        "required": [
          "hasUsers"
        ],
        "additionalProperties": false,
        "description": "Whether the admin user table has been initialised."
      },
      "MeResponse": {
        "type": "object",
        "properties": {
          "user": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MePayload"
              },
              {
                "type": "null"
              }
            ],
            "description": "The authenticated user, or null if the request is unauthenticated."
          }
        },
        "required": [
          "user"
        ],
        "additionalProperties": false,
        "description": "Response of `GET /api/auth/me` describing the current session, or null when not signed in."
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable identifier for the admin user (prefix `usr_`).",
            "example": "usr_olivia"
          },
          "username": {
            "type": "string",
            "description": "Login name used for local (password) authentication; unique within the deployment.",
            "example": "olivia.admin"
          },
          "email": {
            "description": "Email address, or null when none is set. Set by an admin, or copied from the identity provider (OIDC `email`, SAML email attribute, SCIM `emails`).",
            "example": "olivia@northwind.example",
            "type": [
              "string",
              "null"
            ]
          },
          "avatarUrl": {
            "description": "Path of the profile picture on this API (`GET /api/users/{id}/avatar`), versioned with `?v=` so it changes whenever the picture does; null when the user has none.",
            "example": "/api/users/usr_olivia/avatar?v=9f86d081884c7d65",
            "type": [
              "string",
              "null"
            ]
          },
          "avatarVersion": {
            "description": "Short content hash of the profile picture, for cache-busting a proxied copy; null when the user has none.",
            "example": "9f86d081884c7d65",
            "type": [
              "string",
              "null"
            ]
          },
          "role": {
            "description": "Access level: `admin` (full control), `operator` (manage resources), or `viewer` (read-only).",
            "example": "admin",
            "$ref": "#/components/schemas/Role"
          },
          "roleId": {
            "description": "Effective role id: a custom role id, or the built-in id when no custom role is assigned.",
            "example": "operator",
            "type": "string"
          },
          "roleName": {
            "description": "Display name of the effective role.",
            "example": "operator",
            "type": "string"
          },
          "scopeMode": {
            "description": "`restricted` when the account only sees some tenants.",
            "$ref": "#/components/schemas/ScopeMode"
          },
          "createdAt": {
            "description": "When the user account was created (ISO 8601); null when not recorded.",
            "example": "2026-01-15T09:30:00Z",
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          },
          "updatedAt": {
            "description": "When the user account was last modified (ISO 8601); null if never updated.",
            "example": "2026-02-01T14:20:00Z",
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "username",
          "role"
        ],
        "additionalProperties": {},
        "description": "An admin-console user account (id, login, role, and audit timestamps)."
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "page": {
            "type": "number",
            "description": "1-based page number of the returned results.",
            "example": 1
          },
          "limit": {
            "type": "number",
            "description": "Maximum number of items per page.",
            "example": 50
          },
          "total": {
            "type": "number",
            "description": "Total number of items across all pages.",
            "example": 1
          }
        },
        "required": [
          "page",
          "limit",
          "total"
        ],
        "additionalProperties": false,
        "description": "Pagination metadata describing the current page and page size."
      },
      "UserDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable account identifier.",
            "example": "usr_olivia"
          },
          "username": {
            "type": "string",
            "description": "Login name.",
            "example": "olivia.admin"
          },
          "email": {
            "description": "Email address, or null when none is set. Set by an admin, or copied from the identity provider (OIDC `email`, SAML email attribute, SCIM `emails`).",
            "example": "olivia@northwind.example",
            "type": [
              "string",
              "null"
            ]
          },
          "avatarUrl": {
            "description": "Path of the profile picture on this API (`GET /api/users/{id}/avatar`), versioned with `?v=` so it changes whenever the picture does; null when the user has none.",
            "example": "/api/users/usr_olivia/avatar?v=9f86d081884c7d65",
            "type": [
              "string",
              "null"
            ]
          },
          "avatarVersion": {
            "description": "Short content hash of the profile picture, for cache-busting a proxied copy; null when the user has none.",
            "example": "9f86d081884c7d65",
            "type": [
              "string",
              "null"
            ]
          },
          "emailSource": {
            "description": "`manual` when an admin set the email (SSO never overwrites it); `idp` when it is copied from the identity provider and refreshed at every SSO sign-in or SCIM update; null without an email.",
            "example": "manual",
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "manual",
                  "idp"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "avatarSource": {
            "description": "`upload` when a person uploaded the picture (SSO never replaces it); `idp` when it was fetched from the identity provider’s picture URL; null without a picture.",
            "example": "upload",
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "upload",
                  "idp"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "role": {
            "type": "string",
            "description": "Access level.",
            "example": "admin"
          },
          "roleId": {
            "description": "Effective role: a custom role id, or the built-in id when none is assigned.",
            "example": "admin",
            "type": "string"
          },
          "roleName": {
            "description": "Display name of the effective role.",
            "example": "admin",
            "type": "string"
          },
          "scope": {
            "description": "Which tenants the account may see.",
            "$ref": "#/components/schemas/AccessScope"
          },
          "scopeSource": {
            "description": "`idp` when the scope is re-derived from IdP scope rules on every SSO login; `manual` when an admin set it.",
            "example": "manual",
            "type": "string",
            "enum": [
              "manual",
              "idp"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the account was created (ISO 8601).",
            "example": "2026-01-04T10:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the account was last modified (ISO 8601).",
            "example": "2026-02-11T16:30:00.000Z"
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IdentityLink"
            },
            "description": "Identity-provider links for this account; empty for a local password account.",
            "example": []
          },
          "ssoOnly": {
            "type": "boolean",
            "description": "True when the account signs in only through an identity provider. SCIM- and JIT-provisioned accounts are given an unusable random password, so this is derived from the presence of links rather than from the stored hash.",
            "example": false
          },
          "isLocalAdmin": {
            "type": "boolean",
            "description": "True when this is a password-usable local admin (role `admin` with no identity links) — the set `assertBreakGlassPreserved` refuses to empty.",
            "example": true
          },
          "isPinnedBreakGlass": {
            "type": "boolean",
            "description": "True when `auth.break_glass_user_id` names this account, which lets it sign in with a password even while local login is disabled.",
            "example": false
          }
        },
        "required": [
          "id",
          "username",
          "role",
          "createdAt",
          "updatedAt",
          "links",
          "ssoOnly",
          "isLocalAdmin",
          "isPinnedBreakGlass"
        ],
        "additionalProperties": false,
        "description": "One console account with its identity links and break-glass status."
      },
      "IdentityLink": {
        "type": "object",
        "properties": {
          "providerId": {
            "type": "string",
            "description": "Identity provider this link belongs to.",
            "example": "idp_okta"
          },
          "providerName": {
            "description": "Display name of the provider, or null if it has since been removed.",
            "example": "Okta",
            "type": [
              "string",
              "null"
            ]
          },
          "externalId": {
            "description": "The subject this account maps to in the identity provider — for SCIM the client's `externalId` or `userName`, for JIT the email the account was provisioned from. Identifying data: present only when the caller passed `include_identity=true`, which writes a `user.pii_reveal` audit entry. Null otherwise.",
            "example": "olivia@northwind.example",
            "type": [
              "string",
              "null"
            ]
          },
          "lastLoginAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When this identity last signed in (ISO 8601), or null if never.",
            "example": "2026-08-27T09:14:00.000Z"
          },
          "scimManaged": {
            "type": "boolean",
            "description": "True when the provider provisions this account over SCIM.",
            "example": true
          }
        },
        "required": [
          "providerId",
          "providerName",
          "externalId",
          "lastLoginAt",
          "scimManaged"
        ],
        "additionalProperties": false,
        "description": "A link between a console account and an identity-provider subject."
      },
      "CreatedUser": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier assigned to the new user (prefix `usr_`).",
            "example": "usr_olivia"
          },
          "username": {
            "type": "string",
            "description": "Login name of the created user.",
            "example": "olivia.admin"
          },
          "role": {
            "description": "Access level granted to the created user.",
            "example": "admin",
            "$ref": "#/components/schemas/Role"
          },
          "email": {
            "description": "Email address, or null when none was given.",
            "example": "olivia@northwind.example",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "username",
          "role"
        ],
        "additionalProperties": false,
        "description": "The newly created user (without credentials)."
      },
      "UserAvatar": {
        "type": "object",
        "properties": {
          "avatarUrl": {
            "type": "string",
            "description": "Where the picture is served, versioned with `?v=` so a change busts caches.",
            "example": "/api/users/usr_olivia/avatar?v=9f86d081884c7d65"
          },
          "avatarVersion": {
            "type": "string",
            "description": "Short content hash of the picture.",
            "example": "9f86d081884c7d65"
          },
          "contentType": {
            "type": "string",
            "enum": [
              "image/png",
              "image/jpeg",
              "image/webp"
            ],
            "description": "Image type identified from the bytes.",
            "example": "image/png"
          },
          "byteSize": {
            "type": "number",
            "description": "Size in bytes.",
            "example": 48213
          },
          "source": {
            "type": "string",
            "enum": [
              "upload",
              "idp"
            ],
            "description": "`upload` for a picture set through this API; `idp` for one fetched from the identity provider.",
            "example": "upload"
          }
        },
        "required": [
          "avatarUrl",
          "avatarVersion",
          "contentType",
          "byteSize",
          "source"
        ],
        "additionalProperties": false,
        "description": "A console user's stored profile picture."
      },
      "PermissionInfo": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Permission identifier.",
            "example": "data:read_pii",
            "$ref": "#/components/schemas/Permission"
          },
          "description": {
            "type": "string",
            "description": "What holding the permission allows.",
            "example": "Reveal masked PII fields in synced records (every reveal is audited)."
          },
          "builtinRoles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Role"
            },
            "description": "Built-in roles that hold this permission.",
            "example": [
              "admin"
            ]
          }
        },
        "required": [
          "id",
          "description",
          "builtinRoles"
        ],
        "additionalProperties": false,
        "description": "A permission from the catalog and which built-in roles hold it."
      },
      "RoleDefinition": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Role id: `admin`, `operator` or `viewer` for built-ins, a UUID for custom roles.",
            "example": "operator"
          },
          "name": {
            "type": "string",
            "description": "Display name; unique, case-insensitively.",
            "example": "Support lead"
          },
          "description": {
            "description": "What the role is for; null when unset.",
            "example": "Reads data for the accounts they support.",
            "type": [
              "string",
              "null"
            ]
          },
          "baseRole": {
            "description": "Built-in level a holder is treated as by role-gated routes (and in the JWT).",
            "example": "operator",
            "$ref": "#/components/schemas/Role"
          },
          "permissions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Permission"
            },
            "description": "Effective permissions. For built-ins these are defined in code.",
            "example": [
              "connections:read",
              "data:read"
            ]
          },
          "isBuiltin": {
            "type": "boolean",
            "description": "True for the three immutable built-in roles.",
            "example": false
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the role was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the role was last changed (ISO 8601).",
            "example": "2026-02-01T14:20:00Z"
          },
          "updatedBy": {
            "description": "User who last changed it; null for seeded built-ins.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "baseRole",
          "permissions",
          "isBuiltin",
          "createdAt",
          "updatedAt",
          "updatedBy"
        ],
        "additionalProperties": false,
        "description": "A built-in or custom role and the permissions it grants."
      },
      "UserScope": {
        "type": "object",
        "properties": {
          "mode": {
            "description": "`all` sees every tenant; `restricted` only the tenants in `grants`.",
            "example": "restricted",
            "$ref": "#/components/schemas/ScopeMode"
          },
          "grants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScopeGrantOutput"
            },
            "description": "Tenants granted. Empty when `mode` is `all`; a restricted user with none sees nothing.",
            "example": [
              {
                "tenantId": "acme",
                "verticals": "*"
              }
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "manual",
              "idp"
            ],
            "description": "`idp` when IdP scope rules own the scope; `manual` when an admin set it.",
            "example": "manual"
          }
        },
        "required": [
          "mode",
          "grants",
          "source"
        ],
        "additionalProperties": false,
        "description": "A console user's tenant scope and who owns it."
      },
      "VerticalHealth": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the vertical, e.g. `accounting`.",
            "example": "accounting"
          },
          "status": {
            "type": "string",
            "enum": [
              "up",
              "down"
            ],
            "description": "Health of the vertical service: `up` (reachable) or `down`.",
            "example": "up"
          },
          "adapterCount": {
            "type": "number",
            "description": "Number of platform adapters registered for this vertical.",
            "example": 4
          },
          "error": {
            "description": "Error detail when the vertical is `down`; absent when healthy.",
            "example": "adapter timeout",
            "type": "string"
          }
        },
        "required": [
          "name",
          "status",
          "adapterCount"
        ],
        "additionalProperties": {},
        "description": "Health summary for a single vertical service and its registered adapters."
      },
      "Connection": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the connection (prefix `conn_`).",
            "example": "conn_1042"
          },
          "platform": {
            "type": "string",
            "description": "Slug of the connected platform/adapter, e.g. `xero`.",
            "example": "xero"
          },
          "vertical": {
            "type": "string",
            "description": "Vertical the platform belongs to, e.g. `accounting`.",
            "example": "accounting"
          },
          "tenantId": {
            "description": "Tenant (operator customer) that owns this connection; null when the connection is not scoped to a tenant.",
            "example": "acme",
            "type": [
              "string",
              "null"
            ]
          },
          "label": {
            "description": "Human-friendly name for the connection; null if unset.",
            "example": "Acme onboarding",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "description": "Credential health: `valid`, `expiring_soon`, `expired` (customer must re-authorize), or `platform_error` (the platform OAuth client credentials were rejected — operator must fix the client id/secret).",
            "example": "valid",
            "$ref": "#/components/schemas/ConnectionStatus"
          },
          "expiresAt": {
            "description": "When the connection credentials expire (ISO 8601); null if they do not expire.",
            "example": "2026-03-01T09:30:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "description": "When the connection was first established (ISO 8601).",
            "example": "2026-01-15T09:30:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "description": "When the connection was last modified (ISO 8601).",
            "example": "2026-02-01T10:00:00.000Z"
          },
          "lastRefreshAt": {
            "description": "When the connection token was last refreshed (ISO 8601); null if never refreshed.",
            "example": "2026-02-01T14:20:00Z",
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          },
          "lastRefreshStatus": {
            "description": "Outcome of the most recent token refresh attempt; null if never refreshed.",
            "example": "ok",
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "ok",
                  "failed",
                  "expired",
                  "platform_error"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "lastRefreshError": {
            "description": "Why the most recent refresh attempt failed — the OAuth error code, its description and the HTTP status. Null when the last attempt succeeded. Never contains the response body or request headers.",
            "example": "invalid_grant — Refresh token has expired — HTTP 400",
            "type": [
              "string",
              "null"
            ]
          },
          "syncMode": {
            "description": "How often the connection is re-synced: `default`, `custom`, `trigger_only` or `once`. See `ConnectionSyncSchedule`.",
            "example": "default",
            "type": "string",
            "enum": [
              "default",
              "custom",
              "trigger_only",
              "once"
            ]
          },
          "syncIntervalMinutes": {
            "description": "Minutes between syncs for a `custom` schedule; null otherwise.",
            "example": null,
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "sync": {
            "description": "Last and next sync as the scheduler sees them; null when the deployment runs in passthrough mode and syncs nothing.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ConnectionSyncState"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "platform",
          "vertical",
          "status",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": {},
        "description": "A live platform connection (OAuth/credential link) owned by a tenant, with its credential health."
      },
      "ConnectionStatus": {
        "type": "string",
        "enum": [
          "valid",
          "expiring_soon",
          "expired",
          "platform_error"
        ]
      },
      "ConnectionSyncState": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "default",
              "custom",
              "trigger_only",
              "once"
            ],
            "description": "The schedule in force.",
            "example": "default"
          },
          "intervalMinutes": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "The connection’s own interval; null unless `mode` is `custom`.",
            "example": null
          },
          "effectiveIntervalMinutes": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "The interval that applies — the custom one or the deployment’s; null for `trigger_only` and `once`.",
            "example": 360
          },
          "defaultIntervalMinutes": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "The deployment interval, for labelling the default choice.",
            "example": 360
          },
          "lastSyncedAt": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "When the last successful sync finished (epoch ms); null if never.",
            "example": 1769949600000
          },
          "lastAttemptAt": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "When the last sync of any outcome finished (epoch ms).",
            "example": 1769949600000
          },
          "lastStatus": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "completed",
                  "failed"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Outcome of the last finished sync.",
            "example": "completed"
          },
          "consecutiveFailures": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Failed syncs since the last success; retries back off from 15 minutes.",
            "example": 0
          },
          "active": {
            "type": "boolean",
            "description": "A sync is pending or running now.",
            "example": false
          },
          "nextSyncAt": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "When the scheduler will next queue a sync (epoch ms); null when it will not on its own — trigger only, a spent one-time sync, a sync in flight, or paused.",
            "example": 1769971200000
          },
          "pausedReason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "needs_reauthorization",
                  "platform_error"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Why an automatic schedule is on hold.",
            "example": null
          }
        },
        "required": [
          "mode",
          "intervalMinutes",
          "effectiveIntervalMinutes",
          "defaultIntervalMinutes",
          "lastSyncedAt",
          "lastAttemptAt",
          "lastStatus",
          "consecutiveFailures",
          "active",
          "nextSyncAt",
          "pausedReason"
        ],
        "additionalProperties": false,
        "description": "A connection’s sync schedule as the scheduler sees it right now."
      },
      "Notification": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Numeric identifier of the notification.",
            "example": 1042
          },
          "type": {
            "type": "string",
            "description": "Notification type code: `vertical_down`, `platform_credentials_invalid`, `credential_expired` or `credential_expiring`.",
            "example": "credential_expiring"
          },
          "vertical": {
            "description": "Vertical the notification relates to; null if not vertical-specific.",
            "example": "accounting",
            "type": [
              "string",
              "null"
            ]
          },
          "connectionId": {
            "description": "Connection the notification concerns; null if not connection-specific.",
            "example": "conn_1042",
            "type": [
              "string",
              "null"
            ]
          },
          "platform": {
            "description": "Platform the notification concerns; null if not platform-specific.",
            "example": "xero",
            "type": [
              "string",
              "null"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human-readable notification text shown in the admin UI.",
            "example": "Connection conn_1042 expires in 3 days."
          },
          "acknowledged": {
            "type": "number",
            "description": "Whether the notification has been acknowledged: 0 = unread, 1 = acknowledged.",
            "example": 0
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the notification was raised (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          }
        },
        "required": [
          "id",
          "type",
          "vertical",
          "connectionId",
          "platform",
          "message",
          "acknowledged",
          "createdAt"
        ],
        "additionalProperties": false,
        "description": "An operator-facing notification, e.g. an alert that a connection is expiring soon."
      },
      "UnreadNotificationCount": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Unacknowledged notifications, excluding `credential_expiring` (which auto-heals within a poll and would keep the badge from ever reaching zero).",
            "example": 2
          }
        },
        "required": [
          "count"
        ],
        "additionalProperties": false,
        "description": "The number the admin UI shows on the header bell."
      },
      "AuditEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Monotonic numeric identifier of the audit-log entry.",
            "example": 1042
          },
          "userId": {
            "type": "string",
            "description": "User who performed the action (prefix `usr_`).",
            "example": "usr_olivia"
          },
          "username": {
            "type": "string",
            "description": "Username of the operator who performed the action, resolved at read time. Falls back to the raw user id when the account has since been deleted, and is the literal `system` for actions taken by a background worker.",
            "example": "olivia"
          },
          "action": {
            "type": "string",
            "description": "Machine-readable action code, e.g. `api_key.mint`, `user.login`.",
            "example": "api_key.mint"
          },
          "vertical": {
            "description": "Vertical the action targeted, if applicable; null otherwise.",
            "example": "accounting",
            "type": [
              "string",
              "null"
            ]
          },
          "targetId": {
            "description": "Identifier of the resource acted upon; null when not resource-specific.",
            "example": "key_1042",
            "type": [
              "string",
              "null"
            ]
          },
          "detail": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AuditDetail"
              },
              {
                "type": "null"
              }
            ],
            "description": "Typed per-action payload (discriminated by `action`, grouped by shape); null when the action carries no extra detail.",
            "example": {
              "action": "api_key.mint"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the action occurred (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          }
        },
        "required": [
          "id",
          "userId",
          "username",
          "action",
          "vertical",
          "targetId",
          "detail",
          "createdAt"
        ],
        "additionalProperties": false,
        "description": "A single audit-log entry recording who did what, to which resource, and when."
      },
      "AuditDetail": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/AuditDetailSchemaMigrate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailUserCreate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailUserUpdate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailActionOnly"
          },
          {
            "$ref": "#/components/schemas/AuditDetailFailures"
          },
          {
            "$ref": "#/components/schemas/AuditDetailSsoLogin"
          },
          {
            "$ref": "#/components/schemas/AuditDetailSsoProviderCreate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailSsoRoleMappingCreate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailProviderId"
          },
          {
            "$ref": "#/components/schemas/AuditDetailNameTenantId"
          },
          {
            "$ref": "#/components/schemas/AuditDetailConnectionSyncSchedule"
          },
          {
            "$ref": "#/components/schemas/AuditDetailOAuthIssuerCreate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailOAuthIssuerUpdate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailOAuthIssuerDelete"
          },
          {
            "$ref": "#/components/schemas/AuditDetailOAuthClientCreate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailOAuthClientRevoke"
          },
          {
            "$ref": "#/components/schemas/AuditDetailApiKeyRotate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailUserAvatarUpdate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailBeforeAfter"
          },
          {
            "$ref": "#/components/schemas/AuditDetailNamePlatform"
          },
          {
            "$ref": "#/components/schemas/AuditDetailAuditExport"
          },
          {
            "$ref": "#/components/schemas/AuditDetailAuditRetentionPrune"
          },
          {
            "$ref": "#/components/schemas/AuditDetailLogoFetchStart"
          },
          {
            "$ref": "#/components/schemas/AuditDetailLogoFetchCancel"
          },
          {
            "$ref": "#/components/schemas/AuditDetailLogoFetchFinish"
          },
          {
            "$ref": "#/components/schemas/AuditDetailLogoFetchPurge"
          },
          {
            "$ref": "#/components/schemas/AuditDetailName"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDomain"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDashboardTaskDismiss"
          },
          {
            "$ref": "#/components/schemas/AuditDetailUserRoleAssign"
          },
          {
            "$ref": "#/components/schemas/AuditDetailModeTenantIds"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDataPiiReveal"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDataExport"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDashboardShare"
          },
          {
            "$ref": "#/components/schemas/AuditDetailSupersetGuestToken"
          },
          {
            "$ref": "#/components/schemas/AuditDetailSupersetRegistrySync"
          },
          {
            "$ref": "#/components/schemas/AuditDetailSupersetShare"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDestinationCreate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDestinationUpdate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDestinationDelete"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDestinationRun"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDestinationBackfill"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDestinationCredentialsRotate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailDestinationTest"
          },
          {
            "$ref": "#/components/schemas/AuditDetailSqlAccessProvision"
          },
          {
            "$ref": "#/components/schemas/AuditDetailSqlAccessPrincipalCreate"
          },
          {
            "$ref": "#/components/schemas/AuditDetailPrincipalIdUsernameSessionsTerminated"
          }
        ],
        "description": "Per-action audit-log detail, keyed by `action`. Branches are grouped by shape: each lists the actions that share its fields, so an `action` value picks exactly one branch.",
        "type": "object",
        "discriminator": {
          "propertyName": "action",
          "mapping": {
            "schema.migrate": "#/components/schemas/AuditDetailSchemaMigrate",
            "user.create": "#/components/schemas/AuditDetailUserCreate",
            "user.update": "#/components/schemas/AuditDetailUserUpdate",
            "user.delete": "#/components/schemas/AuditDetailActionOnly",
            "user.login": "#/components/schemas/AuditDetailActionOnly",
            "sso.provider.update": "#/components/schemas/AuditDetailActionOnly",
            "sso.provider.delete": "#/components/schemas/AuditDetailActionOnly",
            "sso.role_mapping.delete": "#/components/schemas/AuditDetailActionOnly",
            "sso.scim_token.mint": "#/components/schemas/AuditDetailActionOnly",
            "sso.scim_token.revoke": "#/components/schemas/AuditDetailActionOnly",
            "connect_session.create": "#/components/schemas/AuditDetailActionOnly",
            "connect_session.revoke": "#/components/schemas/AuditDetailActionOnly",
            "connection.create": "#/components/schemas/AuditDetailActionOnly",
            "connection.delete": "#/components/schemas/AuditDetailActionOnly",
            "connection.update": "#/components/schemas/AuditDetailActionOnly",
            "api_key.mint": "#/components/schemas/AuditDetailActionOnly",
            "api_key.revoke": "#/components/schemas/AuditDetailActionOnly",
            "end_user.create": "#/components/schemas/AuditDetailActionOnly",
            "end_user.update": "#/components/schemas/AuditDetailActionOnly",
            "end_user.delete": "#/components/schemas/AuditDetailActionOnly",
            "user.pii_reveal": "#/components/schemas/AuditDetailActionOnly",
            "user.avatar_delete": "#/components/schemas/AuditDetailActionOnly",
            "end_user.pii_reveal": "#/components/schemas/AuditDetailActionOnly",
            "end_user_token.mint": "#/components/schemas/AuditDetailActionOnly",
            "end_user_token.revoke": "#/components/schemas/AuditDetailActionOnly",
            "webhook_sub.create": "#/components/schemas/AuditDetailActionOnly",
            "webhook_sub.delete": "#/components/schemas/AuditDetailActionOnly",
            "webhook_sub.pause": "#/components/schemas/AuditDetailActionOnly",
            "webhook_sub.rotate_secret": "#/components/schemas/AuditDetailActionOnly",
            "webhook_sub.update": "#/components/schemas/AuditDetailActionOnly",
            "webhook_sub.test": "#/components/schemas/AuditDetailActionOnly",
            "webhook_delivery.replay": "#/components/schemas/AuditDetailActionOnly",
            "sync_job.create": "#/components/schemas/AuditDetailActionOnly",
            "sync_job.cancel": "#/components/schemas/AuditDetailActionOnly",
            "company_info.update": "#/components/schemas/AuditDetailActionOnly",
            "company_info.reset": "#/components/schemas/AuditDetailActionOnly",
            "adapter.enable": "#/components/schemas/AuditDetailActionOnly",
            "adapter.disable": "#/components/schemas/AuditDetailActionOnly",
            "adapter.config": "#/components/schemas/AuditDetailActionOnly",
            "tenant.delete": "#/components/schemas/AuditDetailActionOnly",
            "dashboard_task.undismiss": "#/components/schemas/AuditDetailActionOnly",
            "role.delete": "#/components/schemas/AuditDetailActionOnly",
            "user.lockout.temporary": "#/components/schemas/AuditDetailFailures",
            "user.lockout.permanent": "#/components/schemas/AuditDetailFailures",
            "sso.login": "#/components/schemas/AuditDetailSsoLogin",
            "sso.provider.create": "#/components/schemas/AuditDetailSsoProviderCreate",
            "sso.role_mapping.create": "#/components/schemas/AuditDetailSsoRoleMappingCreate",
            "sso.scim.provision": "#/components/schemas/AuditDetailProviderId",
            "sso.scim.deprovision": "#/components/schemas/AuditDetailProviderId",
            "sso.scim.group.create": "#/components/schemas/AuditDetailProviderId",
            "sso.scim.group.update": "#/components/schemas/AuditDetailProviderId",
            "sso.scim.group.delete": "#/components/schemas/AuditDetailProviderId",
            "idp.scope_rule.create": "#/components/schemas/AuditDetailProviderId",
            "idp.scope_rule.delete": "#/components/schemas/AuditDetailProviderId",
            "connect_link_template.create": "#/components/schemas/AuditDetailNameTenantId",
            "connect_link_template.update": "#/components/schemas/AuditDetailNameTenantId",
            "connect_link_template.delete": "#/components/schemas/AuditDetailNameTenantId",
            "connection.sync_schedule": "#/components/schemas/AuditDetailConnectionSyncSchedule",
            "oauth_issuer.create": "#/components/schemas/AuditDetailOAuthIssuerCreate",
            "oauth_issuer.update": "#/components/schemas/AuditDetailOAuthIssuerUpdate",
            "oauth_issuer.delete": "#/components/schemas/AuditDetailOAuthIssuerDelete",
            "oauth_client.create": "#/components/schemas/AuditDetailOAuthClientCreate",
            "oauth_client.revoke": "#/components/schemas/AuditDetailOAuthClientRevoke",
            "api_key.rotate": "#/components/schemas/AuditDetailApiKeyRotate",
            "user.avatar_update": "#/components/schemas/AuditDetailUserAvatarUpdate",
            "runtime_setting.update": "#/components/schemas/AuditDetailBeforeAfter",
            "runtime_setting.reset": "#/components/schemas/AuditDetailBeforeAfter",
            "scope_group.create": "#/components/schemas/AuditDetailNamePlatform",
            "scope_group.update": "#/components/schemas/AuditDetailNamePlatform",
            "scope_group.delete": "#/components/schemas/AuditDetailNamePlatform",
            "audit.export": "#/components/schemas/AuditDetailAuditExport",
            "audit.retention.prune": "#/components/schemas/AuditDetailAuditRetentionPrune",
            "logo_fetch.start": "#/components/schemas/AuditDetailLogoFetchStart",
            "logo_fetch.cancel": "#/components/schemas/AuditDetailLogoFetchCancel",
            "logo_fetch.finish": "#/components/schemas/AuditDetailLogoFetchFinish",
            "logo_fetch.purge": "#/components/schemas/AuditDetailLogoFetchPurge",
            "tenant.create": "#/components/schemas/AuditDetailName",
            "tenant.update": "#/components/schemas/AuditDetailName",
            "role.create": "#/components/schemas/AuditDetailName",
            "role.update": "#/components/schemas/AuditDetailName",
            "dashboard.create": "#/components/schemas/AuditDetailName",
            "dashboard.update": "#/components/schemas/AuditDetailName",
            "dashboard.delete": "#/components/schemas/AuditDetailName",
            "tenant_domain.add": "#/components/schemas/AuditDetailDomain",
            "tenant_domain.remove": "#/components/schemas/AuditDetailDomain",
            "dashboard_task.dismiss": "#/components/schemas/AuditDetailDashboardTaskDismiss",
            "user.role_assign": "#/components/schemas/AuditDetailUserRoleAssign",
            "user.scope_update": "#/components/schemas/AuditDetailModeTenantIds",
            "idp.default_scope.update": "#/components/schemas/AuditDetailModeTenantIds",
            "data.pii_reveal": "#/components/schemas/AuditDetailDataPiiReveal",
            "data.export": "#/components/schemas/AuditDetailDataExport",
            "dashboard.share": "#/components/schemas/AuditDetailDashboardShare",
            "superset.guest_token": "#/components/schemas/AuditDetailSupersetGuestToken",
            "superset.registry_sync": "#/components/schemas/AuditDetailSupersetRegistrySync",
            "superset.share": "#/components/schemas/AuditDetailSupersetShare",
            "destination.create": "#/components/schemas/AuditDetailDestinationCreate",
            "destination.update": "#/components/schemas/AuditDetailDestinationUpdate",
            "destination.delete": "#/components/schemas/AuditDetailDestinationDelete",
            "destination.run": "#/components/schemas/AuditDetailDestinationRun",
            "destination.backfill": "#/components/schemas/AuditDetailDestinationBackfill",
            "destination.credentials_rotate": "#/components/schemas/AuditDetailDestinationCredentialsRotate",
            "destination.test": "#/components/schemas/AuditDetailDestinationTest",
            "sql_access.provision": "#/components/schemas/AuditDetailSqlAccessProvision",
            "sql_access.principal_create": "#/components/schemas/AuditDetailSqlAccessPrincipalCreate",
            "sql_access.principal_rotate": "#/components/schemas/AuditDetailPrincipalIdUsernameSessionsTerminated",
            "sql_access.principal_revoke": "#/components/schemas/AuditDetailPrincipalIdUsernameSessionsTerminated"
          }
        }
      },
      "AuditDetailSchemaMigrate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "schema.migrate"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "schema.migrate"
          },
          "version": {
            "type": "number",
            "description": "Schema version that was applied.",
            "example": 12
          },
          "durationMs": {
            "type": "number",
            "description": "How long the migration took, in milliseconds.",
            "example": 184
          }
        },
        "required": [
          "action",
          "version",
          "durationMs"
        ],
        "additionalProperties": false,
        "description": "Audit detail for a schema migration being applied."
      },
      "AuditDetailUserCreate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "user.create"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "user.create"
          },
          "username": {
            "type": "string",
            "description": "Login name of the user that was created.",
            "example": "olivia.admin"
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "operator",
              "viewer"
            ],
            "description": "Role assigned to the new user.",
            "example": "admin"
          },
          "emailSet": {
            "description": "True when the account was created with an email address. The address itself is never recorded.",
            "example": true,
            "type": "boolean"
          }
        },
        "required": [
          "action",
          "username",
          "role"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `user.create`."
      },
      "AuditDetailUserUpdate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "user.update"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "user.update"
          },
          "emailChanged": {
            "description": "True when the update set, changed or cleared the email address. The address itself is never recorded.",
            "example": true,
            "type": "boolean"
          },
          "role": {
            "description": "The new role, when the update changed it.",
            "example": "operator",
            "type": "string"
          },
          "scopeCleared": {
            "description": "True when the change made the user an admin and so lifted their tenant restriction.",
            "example": true,
            "type": "boolean"
          },
          "passwordChanged": {
            "description": "True when the update reset the password. The password itself is never recorded.",
            "example": true,
            "type": "boolean"
          }
        },
        "required": [
          "action"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `user.update`."
      },
      "AuditDetailActionOnly": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "user.delete",
              "user.login",
              "sso.provider.update",
              "sso.provider.delete",
              "sso.role_mapping.delete",
              "sso.scim_token.mint",
              "sso.scim_token.revoke",
              "connect_session.create",
              "connect_session.revoke",
              "connection.create",
              "connection.delete",
              "connection.update",
              "api_key.mint",
              "api_key.revoke",
              "end_user.create",
              "end_user.update",
              "end_user.delete",
              "user.pii_reveal",
              "user.avatar_delete",
              "end_user.pii_reveal",
              "end_user_token.mint",
              "end_user_token.revoke",
              "webhook_sub.create",
              "webhook_sub.delete",
              "webhook_sub.pause",
              "webhook_sub.rotate_secret",
              "webhook_sub.update",
              "webhook_sub.test",
              "webhook_delivery.replay",
              "sync_job.create",
              "sync_job.cancel",
              "company_info.update",
              "company_info.reset",
              "adapter.enable",
              "adapter.disable",
              "adapter.config",
              "tenant.delete",
              "dashboard_task.undismiss",
              "role.delete"
            ],
            "description": "Action code identifying this audit entry. One of: `user.delete`, `user.login`, `sso.provider.update`, `sso.provider.delete`, `sso.role_mapping.delete`, `sso.scim_token.mint`, `sso.scim_token.revoke`, `connect_session.create`, `connect_session.revoke`, `connection.create`, `connection.delete`, `connection.update`, `api_key.mint`, `api_key.revoke`, `end_user.create`, `end_user.update`, `end_user.delete`, `user.pii_reveal`, `user.avatar_delete`, `end_user.pii_reveal`, `end_user_token.mint`, `end_user_token.revoke`, `webhook_sub.create`, `webhook_sub.delete`, `webhook_sub.pause`, `webhook_sub.rotate_secret`, `webhook_sub.update`, `webhook_sub.test`, `webhook_delivery.replay`, `sync_job.create`, `sync_job.cancel`, `company_info.update`, `company_info.reset`, `adapter.enable`, `adapter.disable`, `adapter.config`, `tenant.delete`, `dashboard_task.undismiss`, `role.delete`.",
            "example": "user.delete"
          }
        },
        "required": [
          "action"
        ],
        "additionalProperties": false,
        "description": "Audit detail shape shared by 39 actions (`user.delete`, `user.login`, `sso.provider.update`, `sso.provider.delete`, `sso.role_mapping.delete`, `sso.scim_token.mint`, `sso.scim_token.revoke`, `connect_session.create`, `connect_session.revoke`, `connection.create`, `connection.delete`, `connection.update`, `api_key.mint`, `api_key.revoke`, `end_user.create`, `end_user.update`, `end_user.delete`, `user.pii_reveal`, `user.avatar_delete`, `end_user.pii_reveal`, `end_user_token.mint`, `end_user_token.revoke`, `webhook_sub.create`, `webhook_sub.delete`, `webhook_sub.pause`, `webhook_sub.rotate_secret`, `webhook_sub.update`, `webhook_sub.test`, `webhook_delivery.replay`, `sync_job.create`, `sync_job.cancel`, `company_info.update`, `company_info.reset`, `adapter.enable`, `adapter.disable`, `adapter.config`, `tenant.delete`, `dashboard_task.undismiss`, `role.delete`): the action code alone, no further fields."
      },
      "AuditDetailFailures": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "user.lockout.temporary",
              "user.lockout.permanent"
            ],
            "description": "Action code identifying this audit entry. One of: `user.lockout.temporary`, `user.lockout.permanent`.",
            "example": "user.lockout.temporary"
          },
          "failures": {
            "type": "number",
            "description": "Consecutive failed login attempts that triggered the temporary lockout.",
            "example": 5
          }
        },
        "required": [
          "action",
          "failures"
        ],
        "additionalProperties": false,
        "description": "Audit detail shape shared by 2 actions (`user.lockout.temporary`, `user.lockout.permanent`)."
      },
      "AuditDetailSsoLogin": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "sso.login"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "sso.login"
          },
          "created": {
            "type": "boolean",
            "description": "True if the user was just-in-time provisioned during this login.",
            "example": false
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "operator",
              "viewer"
            ],
            "description": "Role the user holds after this SSO login.",
            "example": "viewer"
          },
          "roleChanged": {
            "description": "True if role mapping changed the user’s role on this login (OIDC/SAML paths only).",
            "example": false,
            "type": "boolean"
          },
          "protocol": {
            "description": "Present and set to `ldap` when the login came via the LDAP path.",
            "example": "ldap",
            "type": "string",
            "const": "ldap"
          }
        },
        "required": [
          "action",
          "created",
          "role"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `sso.login`."
      },
      "AuditDetailSsoProviderCreate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "sso.provider.create"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "sso.provider.create"
          },
          "protocol": {
            "type": "string",
            "enum": [
              "saml",
              "oidc",
              "ldap"
            ],
            "description": "Protocol of the identity provider that was created.",
            "example": "oidc"
          },
          "slug": {
            "type": "string",
            "description": "Slug assigned to the new identity provider.",
            "example": "northwind"
          }
        },
        "required": [
          "action",
          "protocol",
          "slug"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `sso.provider.create`."
      },
      "AuditDetailSsoRoleMappingCreate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "sso.role_mapping.create"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "sso.role_mapping.create"
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "operator",
              "viewer"
            ],
            "description": "Role the created mapping rule grants.",
            "example": "admin"
          }
        },
        "required": [
          "action",
          "role"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `sso.role_mapping.create`."
      },
      "AuditDetailProviderId": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "sso.scim.provision",
              "sso.scim.deprovision",
              "sso.scim.group.create",
              "sso.scim.group.update",
              "sso.scim.group.delete",
              "idp.scope_rule.create",
              "idp.scope_rule.delete"
            ],
            "description": "Action code identifying this audit entry. One of: `sso.scim.provision`, `sso.scim.deprovision`, `sso.scim.group.create`, `sso.scim.group.update`, `sso.scim.group.delete`, `idp.scope_rule.create`, `idp.scope_rule.delete`.",
            "example": "sso.scim.provision"
          },
          "providerId": {
            "type": "string",
            "description": "Identity provider the SCIM operation originated from (prefix `idp_`).",
            "example": "idp_northwind"
          }
        },
        "required": [
          "action",
          "providerId"
        ],
        "additionalProperties": false,
        "description": "Audit detail shape shared by 7 actions (`sso.scim.provision`, `sso.scim.deprovision`, `sso.scim.group.create`, `sso.scim.group.update`, `sso.scim.group.delete`, `idp.scope_rule.create`, `idp.scope_rule.delete`)."
      },
      "AuditDetailNameTenantId": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "connect_link_template.create",
              "connect_link_template.update",
              "connect_link_template.delete"
            ],
            "description": "Action code identifying this audit entry. One of: `connect_link_template.create`, `connect_link_template.update`, `connect_link_template.delete`.",
            "example": "connect_link_template.create"
          },
          "name": {
            "type": "string",
            "description": "Name of the affected connect-link template.",
            "example": "Acme onboarding"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant the template belongs to.",
            "example": "acme"
          }
        },
        "required": [
          "action",
          "name",
          "tenantId"
        ],
        "additionalProperties": false,
        "description": "Audit detail shape shared by 3 actions (`connect_link_template.create`, `connect_link_template.update`, `connect_link_template.delete`)."
      },
      "AuditDetailConnectionSyncSchedule": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "connection.sync_schedule"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "connection.sync_schedule"
          },
          "from": {
            "$ref": "#/components/schemas/AuditConnectionSyncSchedule"
          },
          "to": {
            "$ref": "#/components/schemas/AuditConnectionSyncSchedule"
          }
        },
        "required": [
          "action",
          "from",
          "to"
        ],
        "additionalProperties": false,
        "description": "Audit detail for changing a connection's sync schedule: the schedule before and after."
      },
      "AuditConnectionSyncSchedule": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "default",
              "custom",
              "trigger_only",
              "once"
            ],
            "description": "Sync schedule mode.",
            "example": "custom"
          },
          "intervalMinutes": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Minutes between syncs for a `custom` schedule; null otherwise.",
            "example": 120
          }
        },
        "required": [
          "mode",
          "intervalMinutes"
        ],
        "additionalProperties": false,
        "description": "A connection's sync schedule."
      },
      "AuditDetailOAuthIssuerCreate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "oauth_issuer.create"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "oauth_issuer.create"
          },
          "name": {
            "type": "string",
            "description": "Operator-facing label given to the issuer.",
            "example": "Corp Keycloak"
          },
          "issuer": {
            "type": "string",
            "description": "The iss value tokens must carry.",
            "example": "https://idp.corp.example/realms/main"
          },
          "authorityMode": {
            "type": "string",
            "description": "Where tenant and scopes will come from. `external` is the one worth noticing in an audit trail: it means tokens carry their own authority and cannot be revoked before they expire.",
            "example": "registry"
          }
        },
        "required": [
          "action",
          "name",
          "issuer",
          "authorityMode"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `oauth_issuer.create`."
      },
      "AuditDetailOAuthIssuerUpdate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "oauth_issuer.update"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "oauth_issuer.update"
          },
          "name": {
            "type": "string",
            "description": "Operator-facing label of the issuer.",
            "example": "Corp Keycloak"
          },
          "changed": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Which fields the operator submitted. Never the values, and never a token.",
            "example": [
              "authorityMode",
              "allowedTenants"
            ]
          }
        },
        "required": [
          "action",
          "name",
          "changed"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `oauth_issuer.update`."
      },
      "AuditDetailOAuthIssuerDelete": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "oauth_issuer.delete"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "oauth_issuer.delete"
          },
          "name": {
            "type": "string",
            "description": "Label of the deleted issuer.",
            "example": "Corp Keycloak"
          },
          "issuer": {
            "type": "string",
            "description": "The iss value it accepted.",
            "example": "https://idp.corp.example/realms/main"
          }
        },
        "required": [
          "action",
          "name",
          "issuer"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `oauth_issuer.delete`."
      },
      "AuditDetailOAuthClientCreate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "oauth_client.create"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "oauth_client.create"
          },
          "subject": {
            "type": "string",
            "description": "Subject claim value identifying the service account.",
            "example": "billing-service"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant it authenticates as.",
            "example": "acme"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Scopes granted to it.",
            "example": [
              "customers:read",
              "vertical:read"
            ]
          }
        },
        "required": [
          "action",
          "subject",
          "tenantId",
          "scopes"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `oauth_client.create`."
      },
      "AuditDetailOAuthClientRevoke": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "oauth_client.revoke"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "oauth_client.revoke"
          },
          "subject": {
            "type": "string",
            "description": "Subject claim value of the revoked service account.",
            "example": "billing-service"
          }
        },
        "required": [
          "action",
          "subject"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `oauth_client.revoke`."
      },
      "AuditDetailApiKeyRotate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "api_key.rotate"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "api_key.rotate"
          },
          "replacementId": {
            "description": "Id of the replacement key minted by the rotation.",
            "example": "a81bc81b-dead-4e5d-abff-90865d1e13b1",
            "type": "string"
          },
          "oldKeyRevokeAt": {
            "description": "Epoch ms when the rotated key's grace window ends.",
            "example": 1774137600000,
            "type": "number"
          }
        },
        "required": [
          "action"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `api_key.rotate`."
      },
      "AuditDetailUserAvatarUpdate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "user.avatar_update"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "user.avatar_update"
          },
          "contentType": {
            "type": "string",
            "enum": [
              "image/png",
              "image/jpeg",
              "image/webp"
            ],
            "description": "Image type identified from the uploaded bytes (never the client-declared type).",
            "example": "image/png"
          },
          "byteSize": {
            "type": "number",
            "description": "Size of the stored picture in bytes.",
            "example": 48213
          }
        },
        "required": [
          "action",
          "contentType",
          "byteSize"
        ],
        "additionalProperties": false,
        "description": "Audit detail for a profile picture uploaded to a console account (`targetId` is the account)."
      },
      "AuditDetailBeforeAfter": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "runtime_setting.update",
              "runtime_setting.reset"
            ],
            "description": "Action code identifying this audit entry. One of: `runtime_setting.update`, `runtime_setting.reset`.",
            "example": "runtime_setting.update"
          },
          "before": {
            "description": "Previous value of the setting before the update; type matches the setting.",
            "example": 300
          },
          "after": {
            "description": "New value of the setting after the update; type matches the setting.",
            "example": 600
          }
        },
        "required": [
          "action",
          "before",
          "after"
        ],
        "additionalProperties": false,
        "description": "Audit detail shape shared by 2 actions (`runtime_setting.update`, `runtime_setting.reset`)."
      },
      "AuditDetailNamePlatform": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "scope_group.create",
              "scope_group.update",
              "scope_group.delete"
            ],
            "description": "Action code identifying this audit entry. One of: `scope_group.create`, `scope_group.update`, `scope_group.delete`.",
            "example": "scope_group.create"
          },
          "name": {
            "type": "string",
            "description": "Name of the affected scope group.",
            "example": "Accounting read"
          },
          "platform": {
            "type": "string",
            "description": "Platform slug the scope group targets.",
            "example": "xero"
          }
        },
        "required": [
          "action",
          "name",
          "platform"
        ],
        "additionalProperties": false,
        "description": "Audit detail shape shared by 3 actions (`scope_group.create`, `scope_group.update`, `scope_group.delete`)."
      },
      "AuditDetailAuditExport": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "audit.export"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "audit.export"
          },
          "format": {
            "type": "string",
            "enum": [
              "csv",
              "json"
            ],
            "description": "Export format requested: `csv` or `json`.",
            "example": "csv"
          },
          "count": {
            "type": "number",
            "description": "Number of audit entries included in the export.",
            "example": 1042
          }
        },
        "required": [
          "action",
          "format",
          "count"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `audit.export`."
      },
      "AuditDetailAuditRetentionPrune": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "audit.retention.prune"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "audit.retention.prune"
          },
          "deleted": {
            "type": "number",
            "description": "Number of audit rows pruned by this retention sweep.",
            "example": 128
          },
          "retentionDays": {
            "type": "number",
            "description": "Retention window in days; rows older than this were deleted.",
            "example": 90
          }
        },
        "required": [
          "action",
          "deleted",
          "retentionDays"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `audit.retention.prune`."
      },
      "AuditDetailLogoFetchStart": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "logo_fetch.start"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "logo_fetch.start"
          },
          "jobId": {
            "type": "string",
            "description": "Identifier of the queued logo-fetch job.",
            "example": "lfj_01HQ8ZK"
          },
          "force": {
            "type": "boolean",
            "description": "True when the job refetches logos that are already stored.",
            "example": false
          },
          "vertical": {
            "description": "Vertical the fetch was limited to, or null for every vertical.",
            "example": "accounting",
            "type": [
              "string",
              "null"
            ]
          },
          "slug": {
            "description": "Single platform the fetch was limited to, or null for all of them.",
            "example": "xero",
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "type": "number",
            "description": "Number of platforms the job will consider.",
            "example": 1545
          }
        },
        "required": [
          "action",
          "jobId",
          "force",
          "vertical",
          "slug",
          "total"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `logo_fetch.start`."
      },
      "AuditDetailLogoFetchCancel": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "logo_fetch.cancel"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "logo_fetch.cancel"
          },
          "jobId": {
            "type": "string",
            "description": "Identifier of the cancelled logo-fetch job.",
            "example": "lfj_01HQ8ZK"
          },
          "processed": {
            "type": "number",
            "description": "Platforms processed before the cancel was requested.",
            "example": 412
          }
        },
        "required": [
          "action",
          "jobId",
          "processed"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `logo_fetch.cancel`."
      },
      "AuditDetailLogoFetchFinish": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "logo_fetch.finish"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "logo_fetch.finish"
          },
          "jobId": {
            "type": "string",
            "description": "Identifier of the finished logo-fetch job.",
            "example": "lfj_01HQ8ZK"
          },
          "status": {
            "type": "string",
            "description": "Terminal status: completed, failed, or cancelled.",
            "example": "completed"
          },
          "fetched": {
            "type": "number",
            "description": "Logos downloaded and stored.",
            "example": 1402
          },
          "skipped": {
            "type": "number",
            "description": "Platforms skipped because a logo was already stored.",
            "example": 71
          },
          "notFound": {
            "type": "number",
            "description": "Platforms Brandfetch has no logo for.",
            "example": 70
          },
          "throttled": {
            "type": "number",
            "description": "Platforms abandoned to Brandfetch rate limiting.",
            "example": 2
          },
          "durationMs": {
            "type": "number",
            "description": "Wall-clock duration of the job in milliseconds.",
            "example": 2410000
          }
        },
        "required": [
          "action",
          "jobId",
          "status",
          "fetched",
          "skipped",
          "notFound",
          "throttled",
          "durationMs"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `logo_fetch.finish`."
      },
      "AuditDetailLogoFetchPurge": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "logo_fetch.purge"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "logo_fetch.purge"
          },
          "deleted": {
            "type": "number",
            "description": "Number of stored logo rows deleted.",
            "example": 1402
          }
        },
        "required": [
          "action",
          "deleted"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `logo_fetch.purge`."
      },
      "AuditDetailName": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "tenant.create",
              "tenant.update",
              "role.create",
              "role.update",
              "dashboard.create",
              "dashboard.update",
              "dashboard.delete"
            ],
            "description": "Action code identifying this audit entry. One of: `tenant.create`, `tenant.update`, `role.create`, `role.update`, `dashboard.create`, `dashboard.update`, `dashboard.delete`.",
            "example": "tenant.create"
          },
          "name": {
            "type": "string",
            "description": "Name of the created tenant.",
            "example": "Acme Industries"
          }
        },
        "required": [
          "action",
          "name"
        ],
        "additionalProperties": false,
        "description": "Audit detail shape shared by 7 actions (`tenant.create`, `tenant.update`, `role.create`, `role.update`, `dashboard.create`, `dashboard.update`, `dashboard.delete`)."
      },
      "AuditDetailDomain": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "tenant_domain.add",
              "tenant_domain.remove"
            ],
            "description": "Action code identifying this audit entry. One of: `tenant_domain.add`, `tenant_domain.remove`.",
            "example": "tenant_domain.add"
          },
          "domain": {
            "type": "string",
            "description": "Custom domain attached to the tenant.",
            "example": "dept-a.acme.com"
          }
        },
        "required": [
          "action",
          "domain"
        ],
        "additionalProperties": false,
        "description": "Audit detail shape shared by 2 actions (`tenant_domain.add`, `tenant_domain.remove`)."
      },
      "AuditDetailDashboardTaskDismiss": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "dashboard_task.dismiss"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "dashboard_task.dismiss"
          },
          "keys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Task keys that were cleared.",
            "example": [
              "conn:expired:conn_1042",
              "sync:failed:job_7"
            ]
          },
          "count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many tasks were cleared.",
            "example": 2
          }
        },
        "required": [
          "action",
          "keys",
          "count"
        ],
        "additionalProperties": false,
        "description": "Audit detail for clearing tasks on the dashboard."
      },
      "AuditDetailUserRoleAssign": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "user.role_assign"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "user.role_assign"
          },
          "roleId": {
            "type": "string",
            "description": "Role assigned: a built-in id (`admin`, `operator`, `viewer`) or a custom role id.",
            "example": "operator"
          },
          "baseRole": {
            "type": "string",
            "enum": [
              "admin",
              "operator",
              "viewer"
            ],
            "description": "Base role the user now holds for role-level gates.",
            "example": "operator"
          },
          "scopeCleared": {
            "description": "True when the change made the user an admin and so lifted their tenant restriction.",
            "example": true,
            "type": "boolean"
          }
        },
        "required": [
          "action",
          "roleId",
          "baseRole"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `user.role_assign`."
      },
      "AuditDetailModeTenantIds": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "user.scope_update",
              "idp.default_scope.update"
            ],
            "description": "Action code identifying this audit entry. One of: `user.scope_update`, `idp.default_scope.update`.",
            "example": "user.scope_update"
          },
          "mode": {
            "type": "string",
            "enum": [
              "all",
              "restricted"
            ],
            "description": "`all` (every tenant) or `restricted` to the listed tenants.",
            "example": "restricted"
          },
          "tenantIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tenants granted; empty when `mode` is `all`.",
            "example": [
              "acme"
            ]
          }
        },
        "required": [
          "action",
          "mode",
          "tenantIds"
        ],
        "additionalProperties": false,
        "description": "Audit detail shape shared by 2 actions (`user.scope_update`, `idp.default_scope.update`)."
      },
      "AuditDetailDataPiiReveal": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "data.pii_reveal"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "data.pii_reveal"
          },
          "connectionId": {
            "type": "string",
            "description": "Connection whose stored record was revealed.",
            "example": "9f8e7d6c-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
          },
          "resourceType": {
            "type": "string",
            "description": "Resource type of the record, as stored by the sync worker.",
            "example": "contacts"
          },
          "resourceId": {
            "type": "string",
            "description": "Id of the record whose personal data was shown unmasked.",
            "example": "cont_jane"
          },
          "reason": {
            "description": "Why the operator needed the unmasked record, as they typed it; null when none was given.",
            "example": "Support ticket #4821",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "action",
          "connectionId",
          "resourceType",
          "resourceId",
          "reason"
        ],
        "additionalProperties": false,
        "description": "Audit detail for revealing the personal data in one stored record."
      },
      "AuditDetailDataExport": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "data.export"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "data.export"
          },
          "connectionId": {
            "type": "string",
            "description": "Connection whose stored records were exported.",
            "example": "9f8e7d6c-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
          },
          "resourceType": {
            "type": "string",
            "description": "Resource type exported.",
            "example": "orders"
          },
          "format": {
            "type": "string",
            "enum": [
              "csv",
              "ndjson"
            ],
            "description": "Export format: `csv` or `ndjson`.",
            "example": "csv"
          },
          "includePii": {
            "type": "boolean",
            "description": "True when the export carried unmasked personal data.",
            "example": false
          }
        },
        "required": [
          "action",
          "connectionId",
          "resourceType",
          "format",
          "includePii"
        ],
        "additionalProperties": false,
        "description": "Audit detail for an export of stored records."
      },
      "AuditDetailDashboardShare": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "dashboard.share"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "dashboard.share"
          },
          "name": {
            "type": "string",
            "description": "Name of the dashboard.",
            "example": "Weekly revenue"
          },
          "from": {
            "$ref": "#/components/schemas/AuditDashboardAudience"
          },
          "to": {
            "$ref": "#/components/schemas/AuditDashboardAudience"
          },
          "pinnedFrom": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Pinned tenants before.",
            "example": null
          },
          "pinnedTo": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Pinned tenants after.",
            "example": [
              "acme"
            ]
          }
        },
        "required": [
          "action",
          "name",
          "from",
          "to",
          "pinnedFrom",
          "pinnedTo"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `dashboard.share`."
      },
      "AuditDashboardAudience": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "private",
              "tenants",
              "everyone"
            ],
            "description": "Audience kind.",
            "example": "tenants"
          },
          "tenants": {
            "description": "Tenant ids, for `tenants`.",
            "example": [
              "acme"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "kind"
        ],
        "additionalProperties": false,
        "description": "Who a dashboard is shared with."
      },
      "AuditDetailSupersetGuestToken": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "superset.guest_token"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "superset.guest_token"
          },
          "title": {
            "type": "string",
            "description": "Title of the embedded Superset dashboard.",
            "example": "Connection data overview"
          },
          "restricted": {
            "type": "boolean",
            "description": "True when the token carried a tenant row-level-security clause. Recorded at most once per user and dashboard every 10 minutes.",
            "example": false
          }
        },
        "required": [
          "action",
          "title",
          "restricted"
        ],
        "additionalProperties": false,
        "description": "Audit detail for a guest token minted to embed a Superset dashboard."
      },
      "AuditDetailSupersetRegistrySync": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "superset.registry_sync"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "superset.registry_sync"
          },
          "created": {
            "type": "number",
            "description": "Dashboards added to the registry.",
            "example": 1
          },
          "updated": {
            "type": "number",
            "description": "Dashboards updated in place.",
            "example": 0
          },
          "removed": {
            "type": "number",
            "description": "Dashboards removed (prune).",
            "example": 0
          }
        },
        "required": [
          "action",
          "created",
          "updated",
          "removed"
        ],
        "additionalProperties": false,
        "description": "Audit detail for the superset-bootstrap job syncing the dashboard registry."
      },
      "AuditDetailSupersetShare": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "superset.share"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "superset.share"
          },
          "title": {
            "type": "string",
            "description": "Title of the Superset dashboard.",
            "example": "Revenue"
          },
          "from": {
            "$ref": "#/components/schemas/AuditDashboardAudience"
          },
          "to": {
            "$ref": "#/components/schemas/AuditDashboardAudience"
          },
          "pinnedFrom": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Pinned tenants before.",
            "example": null
          },
          "pinnedTo": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Pinned tenants after.",
            "example": [
              "acme"
            ]
          }
        },
        "required": [
          "action",
          "title",
          "from",
          "to",
          "pinnedFrom",
          "pinnedTo"
        ],
        "additionalProperties": false,
        "description": "Audit detail for `superset.share`."
      },
      "AuditDetailDestinationCreate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "destination.create"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "destination.create"
          },
          "destinationId": {
            "type": "string",
            "description": "Id of the destination.",
            "example": "5b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b"
          },
          "name": {
            "type": "string",
            "description": "Name of the destination.",
            "example": "Lake (prod)"
          },
          "type": {
            "type": "string",
            "description": "Destination type.",
            "example": "s3"
          },
          "includePii": {
            "type": "boolean",
            "description": "True when the destination exports personal data unmasked.",
            "example": false
          },
          "tenants": {
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ],
            "description": "Owner tenants the destination exports, or `*` for every tenant.",
            "example": [
              "acme"
            ]
          }
        },
        "required": [
          "action",
          "destinationId",
          "name",
          "type",
          "includePii",
          "tenants"
        ],
        "additionalProperties": false,
        "description": "Audit detail for creating a destination."
      },
      "AuditDetailDestinationUpdate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "destination.update"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "destination.update"
          },
          "destinationId": {
            "type": "string",
            "description": "Id of the destination.",
            "example": "5b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b"
          },
          "name": {
            "type": "string",
            "description": "Name after the update.",
            "example": "Lake (prod)"
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Settings the update changed (`name`, `config`, `scope`, `includePii`, `intervalSec`, `enabled`).",
            "example": [
              "config",
              "intervalSec"
            ]
          },
          "includePii": {
            "type": "boolean",
            "description": "Whether the destination exports personal data unmasked after the update.",
            "example": false
          }
        },
        "required": [
          "action",
          "destinationId",
          "name",
          "fields",
          "includePii"
        ],
        "additionalProperties": false,
        "description": "Audit detail for changing a destination."
      },
      "AuditDetailDestinationDelete": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "destination.delete"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "destination.delete"
          },
          "destinationId": {
            "type": "string",
            "description": "Id of the destination.",
            "example": "5b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b"
          },
          "name": {
            "description": "Name of the deleted destination; null when it could not be read first.",
            "example": "Lake (prod)",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "action",
          "destinationId",
          "name"
        ],
        "additionalProperties": false,
        "description": "Audit detail for deleting a destination."
      },
      "AuditDetailDestinationRun": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "destination.run"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "destination.run"
          },
          "destinationId": {
            "type": "string",
            "description": "Id of the destination.",
            "example": "5b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b"
          },
          "runId": {
            "type": "string",
            "description": "Id of the run that was started.",
            "example": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
          }
        },
        "required": [
          "action",
          "destinationId",
          "runId"
        ],
        "additionalProperties": false,
        "description": "Audit detail for starting a destination run by hand."
      },
      "AuditDetailDestinationBackfill": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "destination.backfill"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "destination.backfill"
          },
          "destinationId": {
            "type": "string",
            "description": "Id of the destination.",
            "example": "5b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b"
          },
          "vertical": {
            "description": "Vertical whose cursors were reset; null for every vertical.",
            "example": "crm",
            "type": [
              "string",
              "null"
            ]
          },
          "resourceType": {
            "description": "Resource type whose cursor was reset; null for every type.",
            "example": "contacts",
            "type": [
              "string",
              "null"
            ]
          },
          "cursorsReset": {
            "type": "number",
            "description": "Cursors reset.",
            "example": 3
          },
          "runId": {
            "description": "Run started right away; null when none was started.",
            "example": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "action",
          "destinationId",
          "vertical",
          "resourceType",
          "cursorsReset",
          "runId"
        ],
        "additionalProperties": false,
        "description": "Audit detail for a destination backfill."
      },
      "AuditDetailDestinationCredentialsRotate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "destination.credentials_rotate"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "destination.credentials_rotate"
          },
          "destinationId": {
            "type": "string",
            "description": "Id of the destination.",
            "example": "5b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b"
          },
          "secretFields": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of the credential fields now set. Values are never recorded.",
            "example": [
              "accessKeyId",
              "secretAccessKey"
            ]
          }
        },
        "required": [
          "action",
          "destinationId",
          "secretFields"
        ],
        "additionalProperties": false,
        "description": "Audit detail for replacing a destination's credentials."
      },
      "AuditDetailDestinationTest": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "destination.test"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "destination.test"
          },
          "destinationId": {
            "type": "string",
            "description": "Id of the destination.",
            "example": "5b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b"
          },
          "ok": {
            "type": "boolean",
            "description": "Whether the connection test passed.",
            "example": true
          }
        },
        "required": [
          "action",
          "destinationId",
          "ok"
        ],
        "additionalProperties": false,
        "description": "Audit detail for testing a destination."
      },
      "AuditDetailSqlAccessProvision": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "sql_access.provision"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "sql_access.provision"
          },
          "changed": {
            "type": "boolean",
            "description": "Whether anything was (re)created.",
            "example": true
          },
          "version": {
            "description": "Catalog version now deployed.",
            "example": 1,
            "type": [
              "number",
              "null"
            ]
          },
          "breaking": {
            "type": "boolean",
            "description": "True when a new catalog version was cut for a breaking change.",
            "example": false
          }
        },
        "required": [
          "action",
          "changed",
          "version",
          "breaking"
        ],
        "additionalProperties": false,
        "description": "Audit detail for provisioning the SQL views."
      },
      "AuditDetailSqlAccessPrincipalCreate": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "sql_access.principal_create"
            ],
            "description": "Action code identifying this audit variant.",
            "example": "sql_access.principal_create"
          },
          "principalId": {
            "type": "string",
            "description": "Id of the SQL principal.",
            "example": "3f9a1c2b-4d5e-4f60-8a7b-1c2d3e4f5a6b"
          },
          "username": {
            "type": "string",
            "description": "Postgres login name of the principal.",
            "example": "os_sql_metabase_prod_3f9a1c"
          },
          "label": {
            "type": "string",
            "description": "Label of the principal.",
            "example": "Metabase prod"
          },
          "pii": {
            "type": "boolean",
            "description": "True for an unmasked (PII) principal.",
            "example": false
          },
          "tenants": {
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ],
            "description": "Tenants the principal sees, or `*`.",
            "example": [
              "acme"
            ]
          },
          "verticals": {
            "anyOf": [
              {
                "anyOf": [
                  {
                    "type": "string",
                    "const": "*"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Verticals the principal sees; `*` or null for all.",
            "example": [
              "crm"
            ]
          },
          "expiresAt": {
            "description": "When the login expires (ISO 8601); null for never.",
            "example": "2027-01-01T00:00:00.000Z",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "action",
          "principalId",
          "username",
          "label",
          "pii",
          "tenants",
          "verticals",
          "expiresAt"
        ],
        "additionalProperties": false,
        "description": "Audit detail for creating a read-only SQL principal. The password is never recorded."
      },
      "AuditDetailPrincipalIdUsernameSessionsTerminated": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "sql_access.principal_rotate",
              "sql_access.principal_revoke"
            ],
            "description": "Action code identifying this audit entry. One of: `sql_access.principal_rotate`, `sql_access.principal_revoke`.",
            "example": "sql_access.principal_rotate"
          },
          "principalId": {
            "type": "string",
            "description": "Id of the SQL principal.",
            "example": "3f9a1c2b-4d5e-4f60-8a7b-1c2d3e4f5a6b"
          },
          "username": {
            "type": "string",
            "description": "Postgres login name of the principal.",
            "example": "os_sql_metabase_prod_3f9a1c"
          },
          "sessionsTerminated": {
            "description": "Open sessions ended; null when unknown (manual mode).",
            "example": 1,
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "action",
          "principalId",
          "username",
          "sessionsTerminated"
        ],
        "additionalProperties": false,
        "description": "Audit detail shape shared by 2 actions (`sql_access.principal_rotate`, `sql_access.principal_revoke`)."
      },
      "Platform": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Stable machine identifier for the platform/adapter, e.g. `xero`.",
            "example": "xero"
          },
          "name": {
            "type": "string",
            "description": "Human-readable display name of the platform.",
            "example": "Xero"
          },
          "vertical": {
            "type": "string",
            "description": "Vertical the platform belongs to, e.g. `accounting`.",
            "example": "accounting"
          },
          "authType": {
            "description": "Authentication scheme the platform uses, e.g. `oauth2`, `api_key`, `basic`.",
            "example": "oauth2",
            "type": "string"
          },
          "category": {
            "description": "Catalog category used for grouping in the UI.",
            "example": "accounting",
            "type": "string"
          },
          "website": {
            "description": "Marketing/landing URL for the platform.",
            "example": "https://www.xero.com",
            "type": "string"
          },
          "unsupported": {
            "$ref": "#/components/schemas/PlatformUnsupported"
          }
        },
        "required": [
          "slug",
          "name",
          "vertical"
        ],
        "additionalProperties": {},
        "description": "Catalog metadata for an available platform/adapter (name, vertical, auth type)."
      },
      "PlatformUnsupported": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "description": "Why the platform cannot be connected today.",
            "example": "OAuth client must be registered inside each customer's own instance."
          },
          "issueUrl": {
            "description": "Tracking issue for adding support, when one exists.",
            "example": "https://example.com/issues/123",
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "reason"
        ],
        "additionalProperties": false,
        "description": "Present when a platform is listed and viewable but cannot be enabled or connected."
      },
      "PlatformOperatorRow": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Platform slug this operator-config row applies to.",
            "example": "xero"
          },
          "vertical": {
            "description": "Vertical the platform belongs to.",
            "example": "accounting",
            "type": "string"
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the operator has enabled this platform for the vertical.",
            "example": true
          },
          "hasConfig": {
            "type": "boolean",
            "description": "Whether operator credentials/config have been saved for this platform.",
            "example": true
          },
          "unsupported": {
            "$ref": "#/components/schemas/PlatformUnsupported"
          }
        },
        "required": [
          "slug",
          "enabled",
          "hasConfig"
        ],
        "additionalProperties": {},
        "description": "Per-platform enablement/config status within one vertical, as set by the operator."
      },
      "PlatformConfigRedacted": {
        "type": "object",
        "properties": {
          "clientId": {
            "description": "OAuth client ID configured for the platform; null if unset.",
            "example": "opensteward",
            "type": [
              "string",
              "null"
            ]
          },
          "redirectUri": {
            "description": "OAuth redirect/callback URI configured for the platform; null if unset.",
            "example": "https://app.acme.example/return",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Scopes the operator has configured to request; null if defaults apply.",
            "example": [
              "accounting.transactions.read"
            ]
          },
          "hasSecret": {
            "type": "boolean",
            "description": "Whether a client secret is stored; the secret itself is never returned.",
            "example": true
          },
          "recommendedScopes": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Scopes the adapter recommends for this platform; null if none defined.",
            "example": [
              "accounting.transactions.read"
            ]
          },
          "supportsScopeOverride": {
            "description": "Whether the operator may override the default scope set for this platform.",
            "example": true,
            "type": "boolean"
          }
        },
        "required": [
          "clientId",
          "redirectUri",
          "scopes",
          "hasSecret",
          "recommendedScopes"
        ],
        "additionalProperties": false,
        "description": "Operator platform configuration with secrets redacted; `hasSecret` flags whether a secret exists."
      },
      "CompanyInfoRecord": {
        "type": "object",
        "properties": {
          "name": {
            "example": "Acme Industries",
            "type": [
              "string",
              "null"
            ]
          },
          "legalName": {
            "example": "Acme Industries, Inc.",
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "example": "Industrial supplies and equipment.",
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "example": "https://acme.example",
            "type": [
              "string",
              "null"
            ]
          },
          "logoDataUrl": {
            "example": "data:image/svg+xml;base64,PHN2Zz48L3N2Zz4=",
            "type": [
              "string",
              "null"
            ]
          },
          "primaryColor": {
            "example": "#1d4ed8",
            "type": [
              "string",
              "null"
            ]
          },
          "secondaryColor": {
            "example": "#0f172a",
            "type": [
              "string",
              "null"
            ]
          },
          "fontFamily": {
            "example": "Inter, sans-serif",
            "type": [
              "string",
              "null"
            ]
          },
          "fontDataUrl": {
            "example": "data:font/woff2;base64,d09GMgABAAAAAA==",
            "type": [
              "string",
              "null"
            ]
          },
          "fontUrl": {
            "example": "https://fonts.acme.example/inter.css",
            "type": [
              "string",
              "null"
            ]
          },
          "faviconDataUrl": {
            "example": "data:image/png;base64,iVBORw0KGgo=",
            "type": [
              "string",
              "null"
            ]
          },
          "hideAttribution": {
            "example": false,
            "type": [
              "boolean",
              "null"
            ]
          },
          "supportEmail": {
            "example": "jane.doe@acme.example",
            "type": [
              "string",
              "null"
            ]
          },
          "privacyPolicyUrl": {
            "example": "https://acme.example/privacy",
            "type": [
              "string",
              "null"
            ]
          },
          "termsOfServiceUrl": {
            "example": "https://acme.example/terms",
            "type": [
              "string",
              "null"
            ]
          },
          "addressLine1": {
            "example": "2500 Market Street",
            "type": [
              "string",
              "null"
            ]
          },
          "addressLine2": {
            "example": "Suite 300",
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "example": "San Francisco",
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "example": "CA",
            "type": [
              "string",
              "null"
            ]
          },
          "postalCode": {
            "example": "94114",
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "example": "US",
            "type": [
              "string",
              "null"
            ]
          },
          "baseUrl": {
            "example": "https://acme.example",
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the company info was last modified (ISO 8601).",
            "example": "2026-02-01T14:20:00Z"
          },
          "updatedBy": {
            "type": "string",
            "description": "Admin user who last modified the company info (prefix `usr_`).",
            "example": "usr_olivia"
          }
        },
        "required": [
          "updatedAt",
          "updatedBy"
        ],
        "additionalProperties": false,
        "description": "Stored company/branding info plus audit columns for who last changed it and when."
      },
      "PublicCompanyInfo": {
        "type": "object",
        "properties": {
          "name": {
            "description": "Company display name shown on public pages; null if unset.",
            "example": "Northwind Traders",
            "type": [
              "string",
              "null"
            ]
          },
          "logoDataUrl": {
            "description": "Inline data-URL of the company logo; null if unset.",
            "example": "data:image/svg+xml;base64,PHN2Zz48L3N2Zz4=",
            "type": [
              "string",
              "null"
            ]
          },
          "primaryColor": {
            "description": "Primary brand color (CSS hex); null if unset.",
            "example": "#1d4ed8",
            "type": [
              "string",
              "null"
            ]
          },
          "secondaryColor": {
            "description": "Secondary brand color (CSS hex); null if unset.",
            "example": "#0f172a",
            "type": [
              "string",
              "null"
            ]
          },
          "fontFamily": {
            "description": "CSS font-family stack for branded pages; null if unset.",
            "example": "Inter, sans-serif",
            "type": [
              "string",
              "null"
            ]
          },
          "fontDataUrl": {
            "description": "Inline data-URL of a custom web font; null if unset.",
            "example": "data:font/woff2;base64,d09GMgABAAAAAA==",
            "type": [
              "string",
              "null"
            ]
          },
          "fontUrl": {
            "description": "External stylesheet URL for the brand font; null if unset.",
            "example": "https://fonts.acme.example/inter.css",
            "type": [
              "string",
              "null"
            ]
          },
          "faviconDataUrl": {
            "description": "Inline data-URL of the favicon; null if unset.",
            "example": "data:image/png;base64,iVBORw0KGgo=",
            "type": [
              "string",
              "null"
            ]
          },
          "hideAttribution": {
            "type": "boolean",
            "description": "When true, the platform \"powered by\" attribution is hidden on public pages.",
            "example": false
          },
          "supportEmail": {
            "description": "Support contact email shown to customers; null if unset.",
            "example": "support@northwind.example",
            "type": [
              "string",
              "null"
            ]
          },
          "privacyPolicyUrl": {
            "description": "Link to the company privacy policy; null if unset.",
            "example": "https://acme.example/privacy",
            "type": [
              "string",
              "null"
            ]
          },
          "termsOfServiceUrl": {
            "description": "Link to the company terms of service; null if unset.",
            "example": "https://acme.example/terms",
            "type": [
              "string",
              "null"
            ]
          },
          "baseUrl": {
            "description": "Public base URL of the branded application; null if unset.",
            "example": "https://acme.example",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "logoDataUrl",
          "primaryColor",
          "secondaryColor",
          "fontFamily",
          "fontDataUrl",
          "fontUrl",
          "faviconDataUrl",
          "hideAttribution",
          "supportEmail",
          "privacyPolicyUrl",
          "termsOfServiceUrl",
          "baseUrl"
        ],
        "additionalProperties": false,
        "description": "Public, non-sensitive company branding (logo, colors, fonts, support links) for customer-facing pages."
      },
      "EndUserSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the end-user (prefix `cus_`).",
            "example": "cus_4Qm2Xa9Lr"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) the end-user belongs to.",
            "example": "acme"
          },
          "email": {
            "type": "string",
            "description": "Primary email address of the end-user.",
            "example": "jane.doe@acme.example"
          },
          "displayName": {
            "description": "Friendly display name; null if not set.",
            "example": "Jane Doe",
            "type": [
              "string",
              "null"
            ]
          },
          "externalReference": {
            "description": "Operator's own identifier for this end-user in their system; null if unset.",
            "example": "acme-industries",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the end-user record was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the end-user record was last modified (ISO 8601).",
            "example": "2026-02-01T14:20:00Z"
          }
        },
        "required": [
          "id",
          "tenantId",
          "email",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": {},
        "description": "An end-user (the operator's customer) in summary form, without PII or related records."
      },
      "EndUserDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the end-user (prefix `cus_`).",
            "example": "cus_4Qm2Xa9Lr"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) the end-user belongs to.",
            "example": "acme"
          },
          "email": {
            "type": "string",
            "description": "Primary email address of the end-user.",
            "example": "jane.doe@acme.example"
          },
          "displayName": {
            "description": "Friendly display name; null if not set.",
            "example": "Jane Doe",
            "type": [
              "string",
              "null"
            ]
          },
          "externalReference": {
            "description": "Operator's own identifier for this end-user; null if unset.",
            "example": "acme-industries",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the end-user record was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the end-user record was last modified (ISO 8601).",
            "example": "2026-02-01T14:20:00Z"
          },
          "pii": {
            "description": "PII for the end-user; present only when requested and available.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/EndUserPiiOutput"
              },
              {
                "type": "null"
              }
            ]
          },
          "sessions": {
            "description": "The end-user's connect sessions.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConnectSession"
            }
          },
          "connections": {
            "description": "The end-user's active platform connections.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Identifier of the connection (prefix `conn_`).",
                  "example": "conn_1042"
                },
                "vertical": {
                  "description": "Vertical of the connected platform; null if unknown.",
                  "example": "accounting",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "platform": {
                  "type": "string",
                  "description": "Slug of the connected platform.",
                  "example": "xero"
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "When the connection was established (ISO 8601).",
                  "example": "2026-01-15T09:30:00Z"
                }
              },
              "required": [
                "id",
                "platform",
                "createdAt"
              ],
              "additionalProperties": {}
            }
          }
        },
        "required": [
          "id",
          "tenantId",
          "email",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": {},
        "description": "Full end-user record including optional PII, connect sessions, and connections."
      },
      "ConnectSession": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the connect session (prefix `cs_`).",
            "example": "cs_8f3a2b9c4d"
          },
          "token": {
            "type": "string",
            "description": "Public link token embedded in the shareable connect URL (prefix `cl_`).",
            "example": "cl_8f3a2b9c4d"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) the session belongs to.",
            "example": "acme"
          },
          "endUserId": {
            "description": "End-user this session is bound to; null for self-register links not yet claimed.",
            "example": "cus_4Qm2Xa9Lr",
            "type": [
              "string",
              "null"
            ]
          },
          "label": {
            "type": "string",
            "description": "Human-friendly label for the session, shown in the admin UI.",
            "example": "Acme onboarding"
          },
          "allowedVerticals": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Verticals the customer may connect within this session.",
            "example": [
              "accounting"
            ]
          },
          "allowedPlatforms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AllowedPlatformOutput"
            },
            "description": "Specific platforms the customer may connect within this session.",
            "example": [
              {
                "vertical": "accounting",
                "slug": "xero"
              }
            ]
          },
          "redirectUrl": {
            "description": "URL the customer returns to after connecting; null to use the default.",
            "example": "https://app.acme.example/return",
            "type": [
              "string",
              "null"
            ]
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the connect link expires and can no longer be used (ISO 8601).",
            "example": "2026-02-08T09:30:00Z"
          },
          "consumedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the link was consumed by a successful connection; null while still active.",
            "example": null
          },
          "connectionId": {
            "description": "Connection created when the session was completed; null if not yet connected.",
            "example": "conn_1042",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the session was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "createdBy": {
            "description": "Admin user who created the session; null if system-generated.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "description": "Lifecycle state: `active`, `consumed`, or `expired`.",
            "example": "active",
            "$ref": "#/components/schemas/ConnectSessionStatus"
          },
          "oneTimeOnly": {
            "description": "When true, the link is consumed after a single successful connection.",
            "example": false,
            "type": "boolean"
          },
          "url": {
            "description": "Full shareable connect URL the customer opens to start connecting.",
            "example": "https://connect.northwind.example/cl_8f3a2b9c4d",
            "type": "string"
          }
        },
        "required": [
          "id",
          "token",
          "tenantId",
          "endUserId",
          "label",
          "allowedVerticals",
          "allowedPlatforms",
          "redirectUrl",
          "expiresAt",
          "consumedAt",
          "connectionId",
          "createdAt",
          "createdBy",
          "status"
        ],
        "additionalProperties": {},
        "description": "A connect session: a shareable, time-limited link through which an end-user connects a platform."
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the API key record (prefix `key_`).",
            "example": "key_1042"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) the key authenticates as.",
            "example": "acme"
          },
          "prefix": {
            "type": "string",
            "description": "Public, non-secret key prefix shown in listings; the full secret is returned only once, at creation.",
            "example": "osk_acme_8f3a"
          },
          "label": {
            "description": "Human-friendly label for the key; null if unlabeled.",
            "example": "Production key",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Permission scopes granted to this key.",
            "example": [
              "customers:read",
              "connections:read"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ],
            "description": "Which surface the key addresses. `live` keys authenticate `/v1/*`; `test` keys authenticate the `/test/v1/*` sandbox. A key without a recorded mode reads as `live`.",
            "example": "live"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the key was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "lastUsedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the key was last used to authenticate a request; null if never used.",
            "example": "2026-02-01T14:20:00Z"
          },
          "revokedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the key was revoked; null while the key is active.",
            "example": null
          },
          "expiresAt": {
            "description": "Hard expiry; past it the key no longer authenticates. Null = never expires.",
            "example": null,
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          },
          "revokeAt": {
            "description": "Scheduled revocation from a rotation grace window; the key keeps working until then. Null unless the key has been rotated.",
            "example": null,
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          },
          "rotatedFrom": {
            "description": "Id of the key this one replaced, when minted by a rotation.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "tenantId",
          "prefix",
          "label",
          "scopes",
          "mode",
          "createdAt",
          "lastUsedAt",
          "revokedAt"
        ],
        "additionalProperties": {},
        "description": "A tenant-scoped API key for authenticating to the public/dev API. The secret is shown only at mint time."
      },
      "ApiKeyMint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the API key record (prefix `key_`).",
            "example": "key_1042"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) the key authenticates as.",
            "example": "acme"
          },
          "prefix": {
            "type": "string",
            "description": "Public, non-secret key prefix shown in listings; the full secret is returned only once, at creation.",
            "example": "osk_acme_8f3a"
          },
          "label": {
            "description": "Human-friendly label for the key; null if unlabeled.",
            "example": "Production key",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Permission scopes granted to this key.",
            "example": [
              "customers:read",
              "connections:read"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ],
            "description": "Which surface the key addresses. `live` keys authenticate `/v1/*`; `test` keys authenticate the `/test/v1/*` sandbox. A key without a recorded mode reads as `live`.",
            "example": "live"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the key was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "lastUsedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the key was last used to authenticate a request; null if never used.",
            "example": "2026-02-01T14:20:00Z"
          },
          "revokedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the key was revoked; null while the key is active.",
            "example": null
          },
          "expiresAt": {
            "description": "Hard expiry; past it the key no longer authenticates. Null = never expires.",
            "example": null,
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          },
          "revokeAt": {
            "description": "Scheduled revocation from a rotation grace window; the key keeps working until then. Null unless the key has been rotated.",
            "example": null,
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          },
          "rotatedFrom": {
            "description": "Id of the key this one replaced, when minted by a rotation.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "plaintext": {
            "type": "string",
            "description": "The full plaintext API key; shown only once at mint time and never retrievable again.",
            "example": "osk_acme_8f3a2b9c4d5e6f7a8b9c0d1e"
          }
        },
        "required": [
          "id",
          "tenantId",
          "prefix",
          "label",
          "scopes",
          "mode",
          "createdAt",
          "lastUsedAt",
          "revokedAt",
          "plaintext"
        ],
        "additionalProperties": {},
        "description": "API key with the plaintext value (returned once at mint time)."
      },
      "ApiKeyRotate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the API key record (prefix `key_`).",
            "example": "key_1042"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) the key authenticates as.",
            "example": "acme"
          },
          "prefix": {
            "type": "string",
            "description": "Public, non-secret key prefix shown in listings; the full secret is returned only once, at creation.",
            "example": "osk_acme_8f3a"
          },
          "label": {
            "description": "Human-friendly label for the key; null if unlabeled.",
            "example": "Production key",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Permission scopes granted to this key.",
            "example": [
              "customers:read",
              "connections:read"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ],
            "description": "Which surface the key addresses. `live` keys authenticate `/v1/*`; `test` keys authenticate the `/test/v1/*` sandbox. A key without a recorded mode reads as `live`.",
            "example": "live"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the key was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "lastUsedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the key was last used to authenticate a request; null if never used.",
            "example": "2026-02-01T14:20:00Z"
          },
          "revokedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the key was revoked; null while the key is active.",
            "example": null
          },
          "expiresAt": {
            "description": "Hard expiry; past it the key no longer authenticates. Null = never expires.",
            "example": null,
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          },
          "revokeAt": {
            "description": "Scheduled revocation from a rotation grace window; the key keeps working until then. Null unless the key has been rotated.",
            "example": null,
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          },
          "rotatedFrom": {
            "description": "Id of the key this one replaced, when minted by a rotation.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "plaintext": {
            "type": "string",
            "description": "The full plaintext API key; shown only once at mint time and never retrievable again.",
            "example": "osk_acme_8f3a2b9c4d5e6f7a8b9c0d1e"
          },
          "oldKeyRevokeAt": {
            "type": "number",
            "description": "Epoch ms when the replaced key stops verifying — the end of the rotation grace window in which both keys work.",
            "example": 1774137600000
          }
        },
        "required": [
          "id",
          "tenantId",
          "prefix",
          "label",
          "scopes",
          "mode",
          "createdAt",
          "lastUsedAt",
          "revokedAt",
          "plaintext",
          "oldKeyRevokeAt"
        ],
        "additionalProperties": {},
        "description": "The replacement key minted by a rotation (plaintext returned once) plus when the old key dies."
      },
      "OAuthIssuer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the issuer record.",
            "example": "a3f1…"
          },
          "name": {
            "type": "string",
            "description": "Operator-facing label.",
            "example": "Corp Keycloak"
          },
          "preset": {
            "type": "string",
            "description": "Vendor preset the claim names were seeded from, or `generic`.",
            "example": "keycloak"
          },
          "issuer": {
            "type": "string",
            "description": "The exact `iss` value tokens must carry.",
            "example": "https://idp.corp.example/realms/main"
          },
          "jwksUri": {
            "type": "string",
            "description": "Where the issuer publishes its signing keys; resolved from its discovery document.",
            "example": "https://idp.corp.example/realms/main/protocol/openid-connect/certs"
          },
          "audience": {
            "type": "string",
            "description": "The exact `aud` value tokens must carry. Never blank — without it every token the issuer ever minted would be accepted.",
            "example": "https://opensteward.corp.internal"
          },
          "subjectClaim": {
            "type": "string",
            "description": "Which claim names the calling client.",
            "example": "azp"
          },
          "scopeClaim": {
            "type": "string",
            "description": "Which claim carries the token scopes. Dotted paths are read.",
            "example": "realm_access.roles"
          },
          "algorithms": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Signature algorithms accepted. Asymmetric only.",
            "example": [
              "RS256",
              "ES256"
            ]
          },
          "authorityMode": {
            "type": "string",
            "enum": [
              "registry",
              "intersect",
              "external"
            ],
            "description": "Where tenant and scopes come from. `registry`: the client row decides, and deleting it cuts off a live token. `intersect`: the row is the ceiling and the token may narrow it. `external`: the token decides both, and nothing can revoke it before it expires.",
            "example": "registry"
          },
          "tenantClaim": {
            "description": "External mode only: which claim names the tenant. Null otherwise.",
            "example": "https://opensteward/tenant",
            "type": [
              "string",
              "null"
            ]
          },
          "allowedTenants": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "External mode only: tenant values this issuer may assert. Empty admits nobody, never everybody.",
            "example": [
              "acme"
            ]
          },
          "maxTokenLifetimeS": {
            "type": "number",
            "description": "External mode only: refuse a token whose `exp - iat` exceeds this. The only lever over a credential nothing can revoke.",
            "example": 3600
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether tokens from it are accepted.",
            "example": true
          },
          "lastVerifiedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When a real token from this issuer last verified. Null means it has never admitted anybody, which is what blocks disabling API keys.",
            "example": "2026-08-29T10:00:00Z"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the issuer was registered.",
            "example": "2026-08-01T09:00:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it was last changed.",
            "example": "2026-08-20T09:00:00Z"
          }
        },
        "required": [
          "id",
          "name",
          "preset",
          "issuer",
          "jwksUri",
          "audience",
          "subjectClaim",
          "scopeClaim",
          "algorithms",
          "authorityMode",
          "tenantClaim",
          "allowedTenants",
          "maxTokenLifetimeS",
          "enabled",
          "lastVerifiedAt",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false,
        "description": "An identity provider whose tokens the developer API accepts."
      },
      "OAuthReadiness": {
        "type": "object",
        "properties": {
          "ready": {
            "type": "boolean",
            "description": "Whether an OIDC token could actually admit somebody right now.",
            "example": true
          },
          "reason": {
            "type": "string",
            "description": "Why, in words — shown to the operator when disabling API keys is refused.",
            "example": "Corp Keycloak is configured and has verified a token."
          }
        },
        "required": [
          "ready",
          "reason"
        ],
        "additionalProperties": false,
        "description": "Whether OIDC bearer auth is usable. Checked before allowing an operator to disable API keys, so that switch cannot lock every developer out."
      },
      "OAuthPreset": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Preset identifier.",
            "example": "keycloak"
          },
          "label": {
            "type": "string",
            "description": "Vendor name.",
            "example": "Keycloak"
          },
          "issuerHint": {
            "type": "string",
            "description": "Shape of that vendor's issuer URL.",
            "example": "https://{host}/realms/{realm}"
          },
          "subjectClaim": {
            "type": "string",
            "description": "Default subject claim for this vendor.",
            "example": "azp"
          },
          "scopeClaim": {
            "type": "string",
            "description": "Default scope claim for this vendor.",
            "example": "realm_access.roles"
          },
          "note": {
            "description": "Vendor-specific caveat worth reading before saving.",
            "example": "A v1.0 token carries iss=https://sts.windows.net/{tenantId}/ even when the v2.0 endpoint is configured, and will be rejected.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "label",
          "issuerHint",
          "subjectClaim",
          "scopeClaim"
        ],
        "additionalProperties": false,
        "description": "Claim-name defaults for a known identity provider."
      },
      "OAuthIssuerDetail": {
        "type": "object",
        "properties": {
          "issuer": {
            "$ref": "#/components/schemas/OAuthIssuer"
          },
          "clients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OAuthClient"
            },
            "description": "Service accounts registered against it."
          },
          "rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OAuthScopeRule"
            },
            "description": "Scope mapping rules, ascending priority."
          }
        },
        "required": [
          "issuer",
          "clients",
          "rules"
        ],
        "additionalProperties": false,
        "description": "One issuer with its clients and scope rules."
      },
      "OAuthClient": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the client record.",
            "example": "c7b2…"
          },
          "issuerId": {
            "type": "string",
            "description": "Issuer this client belongs to.",
            "example": "a3f1…"
          },
          "subject": {
            "type": "string",
            "description": "Value of the issuer's subject claim identifying this client.",
            "example": "billing-service"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant the client authenticates as.",
            "example": "acme"
          },
          "label": {
            "description": "Human-friendly label.",
            "example": "Billing service",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Scopes granted — the same vocabulary developer API keys use.",
            "example": [
              "customers:read",
              "vertical:read"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it was registered.",
            "example": "2026-08-01T09:00:00Z"
          },
          "lastUsedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When a token from it last verified.",
            "example": "2026-08-29T10:00:00Z"
          },
          "revokedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When it was revoked. A revoked client stops working immediately, mid-token.",
            "example": null
          }
        },
        "required": [
          "id",
          "issuerId",
          "subject",
          "tenantId",
          "label",
          "scopes",
          "createdAt",
          "lastUsedAt",
          "revokedAt"
        ],
        "additionalProperties": false,
        "description": "A registered service account authenticating with OIDC tokens."
      },
      "OAuthScopeRule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the rule.",
            "example": "r5c9…"
          },
          "issuerId": {
            "type": "string",
            "description": "Issuer the rule belongs to.",
            "example": "a3f1…"
          },
          "priority": {
            "type": "number",
            "description": "Evaluation order, ascending.",
            "example": 0
          },
          "claimValue": {
            "type": "string",
            "description": "A value as it appears in the token's scope claim.",
            "example": "read:ledger"
          },
          "grantedScope": {
            "type": "string",
            "description": "The OpenSteward scope it grants.",
            "example": "vertical:accounting"
          }
        },
        "required": [
          "id",
          "issuerId",
          "priority",
          "claimValue",
          "grantedScope"
        ],
        "additionalProperties": false,
        "description": "Maps the IdP's scope vocabulary onto OpenSteward's. With no rules the claim passes through verbatim; with rules, an unmapped value is dropped."
      },
      "OAuthDiscovery": {
        "type": "object",
        "properties": {
          "issuer": {
            "type": "string",
            "description": "The issuer the document reports.",
            "example": "https://idp.corp.example/realms/main"
          },
          "jwksUri": {
            "type": "string",
            "description": "Where its signing keys are published.",
            "example": "https://idp.corp.example/realms/main/protocol/openid-connect/certs"
          }
        },
        "required": [
          "issuer",
          "jwksUri"
        ],
        "additionalProperties": false,
        "description": "Result of reading an issuer's OpenID discovery document."
      },
      "EndUserToken": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the end-user token record (prefix `eut_`).",
            "example": "eut_1042"
          },
          "endUserId": {
            "type": "string",
            "description": "End-user this token authenticates as (prefix `cus_`).",
            "example": "cus_4Qm2Xa9Lr"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant the end-user belongs to.",
            "example": "acme"
          },
          "prefix": {
            "type": "string",
            "description": "Public, non-secret token prefix shown in listings; the full secret is returned only once, at creation.",
            "example": "osk_acme_8f3a"
          },
          "label": {
            "description": "Human-friendly label for the token; null if unlabeled.",
            "example": "Production key",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Permission scopes granted to this token.",
            "example": [
              "customers:read",
              "connections:read"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the token was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "createdBy": {
            "description": "Admin user who minted the token; null if system-generated.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "lastUsedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the token was last used to authenticate a request; null if never used.",
            "example": "2026-02-01T14:20:00Z"
          },
          "revokedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the token was revoked; null while the token is active.",
            "example": null
          }
        },
        "required": [
          "id",
          "endUserId",
          "tenantId",
          "prefix",
          "label",
          "scopes",
          "createdAt",
          "createdBy",
          "lastUsedAt",
          "revokedAt"
        ],
        "additionalProperties": {},
        "description": "An API token scoped to a single end-user, letting them act on their own connections."
      },
      "EndUserTokenMint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the end-user token record (prefix `eut_`).",
            "example": "eut_1042"
          },
          "endUserId": {
            "type": "string",
            "description": "End-user this token authenticates as (prefix `cus_`).",
            "example": "cus_4Qm2Xa9Lr"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant the end-user belongs to.",
            "example": "acme"
          },
          "prefix": {
            "type": "string",
            "description": "Public, non-secret token prefix shown in listings; the full secret is returned only once, at creation.",
            "example": "osk_acme_8f3a"
          },
          "label": {
            "description": "Human-friendly label for the token; null if unlabeled.",
            "example": "Production key",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Permission scopes granted to this token.",
            "example": [
              "customers:read",
              "connections:read"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the token was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "createdBy": {
            "description": "Admin user who minted the token; null if system-generated.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "lastUsedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the token was last used to authenticate a request; null if never used.",
            "example": "2026-02-01T14:20:00Z"
          },
          "revokedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the token was revoked; null while the token is active.",
            "example": null
          },
          "plaintext": {
            "type": "string",
            "description": "The full plaintext token; shown only once at mint time and never retrievable again.",
            "example": "osk_acme_8f3a2b9c4d5e6f7a8b9c0d1e"
          }
        },
        "required": [
          "id",
          "endUserId",
          "tenantId",
          "prefix",
          "label",
          "scopes",
          "createdAt",
          "createdBy",
          "lastUsedAt",
          "revokedAt",
          "plaintext"
        ],
        "additionalProperties": {},
        "description": "End-user token with the plaintext value (returned once at mint time)."
      },
      "WebhookSubscription": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the webhook subscription (prefix `whs_`).",
            "example": "whs_1042"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) that owns the subscription.",
            "example": "acme"
          },
          "url": {
            "type": "string",
            "description": "HTTPS endpoint that receives event deliveries.",
            "example": "https://hooks.acme.example/opensteward"
          },
          "label": {
            "description": "Human-friendly name for the subscription, or null when it has none. Purely descriptive — nothing routes on it — and what the admin list searches.",
            "example": "Billing service",
            "type": [
              "string",
              "null"
            ]
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Event types this subscription is subscribed to, e.g. `customer.created`.",
            "example": [
              "customer.created"
            ]
          },
          "paused": {
            "description": "Whether deliveries are suspended. A paused subscription is retained and still accepts a test send, but receives no event deliveries. Toggle with `POST /api/webhook-subscriptions/{id}/paused`.",
            "example": false,
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the subscription was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "lastFiredAt": {
            "description": "When an event was last delivered to this endpoint; null if never fired.",
            "example": "2026-02-01T14:20:00Z",
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          },
          "lastStatus": {
            "description": "HTTP status code of the most recent delivery attempt; null if never fired.",
            "example": 200,
            "type": [
              "number",
              "null"
            ]
          },
          "lastError": {
            "description": "Error from the most recent failed delivery; null if the last attempt succeeded.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "format": {
            "type": "string",
            "enum": [
              "opensteward",
              "slack",
              "teams",
              "flat"
            ],
            "description": "Payload shape sent to this endpoint. `opensteward` is the signed event envelope; `slack` renders Slack blocks; `teams` renders an Adaptive Card for a Teams Workflows URL; `flat` is a one-level object with dotted keys.",
            "example": "opensteward"
          },
          "headerNames": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of the custom headers sent with each delivery. Values are stored encrypted and are never returned by the API.",
            "example": [
              "X-Api-Key"
            ]
          }
        },
        "required": [
          "id",
          "tenantId",
          "url",
          "events",
          "createdAt",
          "format",
          "headerNames"
        ],
        "additionalProperties": {},
        "description": "A tenant webhook subscription that receives event deliveries at an HTTPS endpoint."
      },
      "WebhookSubscriptionWithSecret": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the webhook subscription (prefix `whs_`).",
            "example": "whs_1042"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) that owns the subscription.",
            "example": "acme"
          },
          "url": {
            "type": "string",
            "description": "HTTPS endpoint that receives event deliveries.",
            "example": "https://hooks.acme.example/opensteward"
          },
          "label": {
            "description": "Human-friendly name for the subscription, or null when it has none. Purely descriptive — nothing routes on it — and what the admin list searches.",
            "example": "Billing service",
            "type": [
              "string",
              "null"
            ]
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Event types this subscription is subscribed to, e.g. `customer.created`.",
            "example": [
              "customer.created"
            ]
          },
          "paused": {
            "description": "Whether deliveries are suspended. A paused subscription is retained and still accepts a test send, but receives no event deliveries. Toggle with `POST /api/webhook-subscriptions/{id}/paused`.",
            "example": false,
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the subscription was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "lastFiredAt": {
            "description": "When an event was last delivered to this endpoint; null if never fired.",
            "example": "2026-02-01T14:20:00Z",
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ]
          },
          "lastStatus": {
            "description": "HTTP status code of the most recent delivery attempt; null if never fired.",
            "example": 200,
            "type": [
              "number",
              "null"
            ]
          },
          "lastError": {
            "description": "Error from the most recent failed delivery; null if the last attempt succeeded.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "format": {
            "type": "string",
            "enum": [
              "opensteward",
              "slack",
              "teams",
              "flat"
            ],
            "description": "Payload shape sent to this endpoint. `opensteward` is the signed event envelope; `slack` renders Slack blocks; `teams` renders an Adaptive Card for a Teams Workflows URL; `flat` is a one-level object with dotted keys.",
            "example": "opensteward"
          },
          "headerNames": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of the custom headers sent with each delivery. Values are stored encrypted and are never returned by the API.",
            "example": [
              "X-Api-Key"
            ]
          },
          "secret": {
            "type": "string",
            "description": "Shared signing secret used to verify delivery signatures; returned only once at create time.",
            "example": "whsec_8f3a2b9c4d5e6f7a8b9c0d1e"
          }
        },
        "required": [
          "id",
          "tenantId",
          "url",
          "events",
          "createdAt",
          "format",
          "headerNames",
          "secret"
        ],
        "additionalProperties": {},
        "description": "Webhook subscription with the plaintext shared secret (returned once at create time)."
      },
      "WebhookTestResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Subscription the test was sent to.",
            "example": "whs_1042"
          },
          "ok": {
            "type": "boolean",
            "description": "True when the receiver answered 2xx. False means the destination rejected or could not be reached — the answer to the diagnostic, not an API error.",
            "example": true
          },
          "status": {
            "description": "HTTP status the receiver returned, or null when the request never completed.",
            "example": 200,
            "type": [
              "number",
              "null"
            ]
          },
          "format": {
            "type": "string",
            "enum": [
              "opensteward",
              "slack",
              "teams",
              "flat"
            ],
            "description": "Format the test payload was rendered in.",
            "example": "slack"
          },
          "sentBody": {
            "description": "The exact bytes sent, so the payload can be inspected. Synthetic and carries no secret.",
            "example": "{\"text\":\"Test event from OpenSteward\"}",
            "type": "string"
          },
          "error": {
            "description": "Why the request never completed, when it did not (DNS failure, timeout, blocked address).",
            "example": "getaddrinfo ENOTFOUND hooks.example",
            "type": "string"
          }
        },
        "required": [
          "id",
          "ok",
          "status",
          "format"
        ],
        "additionalProperties": {},
        "description": "Outcome of sending one synthetic test event to a webhook subscription."
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the delivery attempt record (prefix `whd_`).",
            "example": "whd_1042"
          },
          "subscriptionId": {
            "type": "string",
            "description": "Subscription this delivery belongs to (prefix `whs_`).",
            "example": "whs_1042"
          },
          "eventId": {
            "type": "string",
            "description": "Identifier of the source event being delivered (prefix `evt_`).",
            "example": "evt_4Qm2Xa9Lr"
          },
          "eventType": {
            "type": "string",
            "description": "Type of the event being delivered, e.g. `customer.created`.",
            "example": "customer.created"
          },
          "url": {
            "type": "string",
            "description": "Destination endpoint the event was delivered to.",
            "example": "https://hooks.acme.example/opensteward"
          },
          "status": {
            "description": "Delivery state: `pending` (will retry), `delivered`, or `dead` (gave up).",
            "example": "delivered",
            "$ref": "#/components/schemas/WebhookDeliveryStatus"
          },
          "attempts": {
            "type": "number",
            "description": "Number of delivery attempts made so far.",
            "example": 1
          },
          "nextAttemptAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the next delivery retry is scheduled (for pending/failed deliveries).",
            "example": "2026-02-01T14:25:00Z"
          },
          "deliveredAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the event was successfully delivered; null if not yet delivered.",
            "example": "2026-02-01T14:20:00Z"
          },
          "lastStatus": {
            "description": "HTTP status code returned by the most recent attempt; null if not yet attempted.",
            "example": 200,
            "type": [
              "number",
              "null"
            ]
          },
          "lastError": {
            "description": "Error message from the most recent failed attempt; null on success.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When this delivery record was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          }
        },
        "required": [
          "id",
          "subscriptionId",
          "eventId",
          "eventType",
          "url",
          "status",
          "attempts",
          "nextAttemptAt",
          "deliveredAt",
          "lastStatus",
          "lastError",
          "createdAt"
        ],
        "additionalProperties": {},
        "description": "A single webhook delivery attempt for one event to one subscription, with retry state."
      },
      "WebhookDeliveryStatus": {
        "type": "string",
        "enum": [
          "pending",
          "delivered",
          "dead"
        ]
      },
      "SyncJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the sync job (prefix `job_`).",
            "example": "job_1042"
          },
          "vertical": {
            "type": "string",
            "description": "Vertical the sync runs against.",
            "example": "accounting"
          },
          "connectionId": {
            "type": "string",
            "description": "Connection whose data is being synced (prefix `conn_`).",
            "example": "conn_1042"
          },
          "platform": {
            "type": "string",
            "description": "Slug of the platform being synced.",
            "example": "xero"
          },
          "tenantId": {
            "description": "Tenant that owns the connection; null for jobs on connections not scoped to a tenant.",
            "example": "acme",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "description": "Job lifecycle state: `pending`, `running`, `completed`, or `failed`.",
            "example": "completed",
            "$ref": "#/components/schemas/SyncJobStatus"
          },
          "progress": {
            "description": "Per-resource progress keyed by resource name (e.g. `transactions`); null before the job starts.",
            "example": {
              "transactions": {
                "synced": 128,
                "status": "completed"
              }
            },
            "anyOf": [
              {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "synced": {
                      "type": "number",
                      "description": "Number of records synced for this resource so far.",
                      "example": 128
                    },
                    "status": {
                      "type": "string",
                      "description": "Per-resource sync status.",
                      "example": "completed"
                    },
                    "error": {
                      "description": "Error encountered syncing this resource, if any.",
                      "example": "rate limited",
                      "type": "string"
                    }
                  },
                  "required": [
                    "synced",
                    "status"
                  ],
                  "additionalProperties": {}
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "error": {
            "description": "Top-level failure reason; null unless the job failed.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "callbackUrl": {
            "description": "URL notified when the job completes; null if no callback was requested.",
            "example": "https://app.acme.example/sync-callback",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "description": "When the job was created/enqueued (ISO 8601).",
            "example": "2026-01-15T09:30:00.000Z"
          },
          "startedAt": {
            "description": "When the job began running; null while still pending.",
            "example": "2026-01-15T09:30:05.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "completedAt": {
            "description": "When the job finished (success or failure); null while still running.",
            "example": "2026-01-15T09:31:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "origin": {
            "description": "Why the job was queued: `manual` (Sync now), `api` (POST /v1/{vertical}/sync), `connect` (after a Connect Link), `boot` (DATA_STORE_AUTO_SYNC_ON_BOOT) or `schedule` (the connection's sync schedule). Null on older jobs.",
            "example": "schedule",
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "manual",
                  "api",
                  "connect",
                  "boot",
                  "schedule"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "vertical",
          "connectionId",
          "platform",
          "status",
          "createdAt"
        ],
        "additionalProperties": {},
        "description": "A background data-sync job for one connection, with per-resource progress and lifecycle timestamps."
      },
      "DataStoreMetrics": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "description": "Backing store driver in use, e.g. `sqlite` or `postgres`.",
            "example": "sqlite"
          },
          "path": {
            "type": "string",
            "description": "Filesystem path or connection target of the data store.",
            "example": "/var/lib/opensteward/data.db"
          },
          "rows": {
            "type": "object",
            "properties": {
              "total": {
                "type": "number",
                "description": "Total number of synced data rows across all verticals.",
                "example": 1280
              },
              "per_vertical": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "number"
                },
                "description": "Row counts keyed by vertical.",
                "example": {
                  "accounting": 1280
                }
              },
              "oldest_age_ms": {
                "description": "Age of the oldest stored row in milliseconds; null if the store is empty.",
                "example": 1480200000,
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "total",
              "per_vertical",
              "oldest_age_ms"
            ],
            "additionalProperties": {},
            "description": "Aggregate counts of stored data rows."
          },
          "sync_jobs": {
            "type": "object",
            "properties": {
              "pending": {
                "type": "number",
                "description": "Number of sync jobs currently queued but not started.",
                "example": 0
              },
              "running": {
                "type": "number",
                "description": "Number of sync jobs currently executing.",
                "example": 1
              },
              "failed_recent": {
                "type": "number",
                "description": "Number of jobs that failed in the recent window.",
                "example": 0
              },
              "per_vertical": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "number"
                  }
                },
                "description": "Job counts keyed by vertical, then by status.",
                "example": {
                  "accounting": {
                    "completed": 12
                  }
                }
              }
            },
            "required": [
              "pending",
              "running",
              "failed_recent",
              "per_vertical"
            ],
            "additionalProperties": {},
            "description": "Sync-job counts by state and vertical."
          },
          "db_size_bytes": {
            "description": "On-disk size of the data store in bytes; null if not measurable.",
            "example": 2097152,
            "type": [
              "number",
              "null"
            ]
          },
          "db_size_mb": {
            "description": "On-disk size of the data store in megabytes; null if not measurable.",
            "example": 2,
            "type": [
              "number",
              "null"
            ]
          },
          "timestamp": {
            "type": "string",
            "description": "When these metrics were sampled (ISO 8601).",
            "example": "2026-01-15T09:30:00.000Z"
          }
        },
        "required": [
          "mode",
          "path",
          "rows",
          "sync_jobs",
          "db_size_bytes",
          "db_size_mb",
          "timestamp"
        ],
        "additionalProperties": {},
        "description": "Operational metrics for the synced-data store: row counts, sync-job counts, and storage size."
      },
      "ScopeGroup": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Numeric identifier of the scope group.",
            "example": 7
          },
          "vertical": {
            "type": "string",
            "description": "Vertical the scope group applies to.",
            "example": "accounting"
          },
          "platform": {
            "type": "string",
            "description": "Platform slug the scope group applies to.",
            "example": "xero"
          },
          "name": {
            "type": "string",
            "description": "Human-friendly label for the named bundle of scopes.",
            "example": "Accounting read"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Platform scopes/permissions included in this group.",
            "example": [
              "accounting.transactions.read"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the scope group was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          }
        },
        "required": [
          "id",
          "vertical",
          "platform",
          "name",
          "scopes",
          "createdAt"
        ],
        "additionalProperties": false,
        "description": "A reusable, named bundle of platform scopes that can be attached to connect links."
      },
      "ConnectLinkTemplate": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ConnectLinkTemplatePinned"
          },
          {
            "$ref": "#/components/schemas/ConnectLinkTemplatePicks"
          },
          {
            "$ref": "#/components/schemas/ConnectLinkTemplateSelfRegister"
          }
        ],
        "description": "Connect Link template, keyed by `linkMode`.",
        "type": "object",
        "discriminator": {
          "propertyName": "linkMode",
          "mapping": {
            "pinned": "#/components/schemas/ConnectLinkTemplatePinned",
            "customer-picks-adapter": "#/components/schemas/ConnectLinkTemplatePicks",
            "self-register": "#/components/schemas/ConnectLinkTemplateSelfRegister"
          }
        }
      },
      "ConnectLinkTemplatePinned": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Numeric identifier of the connect-link template.",
            "example": 7
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) that owns this template.",
            "example": "acme"
          },
          "name": {
            "type": "string",
            "description": "Human-friendly name for the template, shown in the admin UI.",
            "example": "Acme onboarding"
          },
          "description": {
            "description": "Optional longer description of the template; null if unset.",
            "example": "Onboarding link for Acme Industries.",
            "type": [
              "string",
              "null"
            ]
          },
          "scopeGroupId": {
            "description": "Scope group whose scopes are requested by links from this template; null for defaults.",
            "example": 7,
            "type": [
              "number",
              "null"
            ]
          },
          "expiryDays": {
            "type": "number",
            "description": "Number of days a generated connect link remains valid before expiring.",
            "example": 7
          },
          "oneTimeOnly": {
            "type": "boolean",
            "description": "When true, links from this template are consumed after a single successful connection.",
            "example": false
          },
          "redirectUrl": {
            "description": "URL the customer is sent to after completing the connection; null to use the default.",
            "example": "https://app.acme.example/return",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "createdBy": {
            "description": "Admin user who created the template; null if created by the system.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "linkMode": {
            "type": "string",
            "const": "pinned",
            "description": "Pinned mode: the adapter is pre-selected, so the customer connects exactly one platform with no choice.",
            "example": "pinned"
          },
          "allowedPlatforms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AllowedPlatformOutput"
            },
            "description": "The single pinned platform the customer will connect.",
            "example": [
              {
                "vertical": "accounting",
                "slug": "xero"
              }
            ]
          },
          "allowedVerticals": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Verticals implied by the pinned platform(s).",
            "example": [
              "accounting"
            ]
          }
        },
        "required": [
          "id",
          "tenantId",
          "name",
          "description",
          "scopeGroupId",
          "expiryDays",
          "oneTimeOnly",
          "redirectUrl",
          "createdAt",
          "createdBy",
          "linkMode",
          "allowedPlatforms",
          "allowedVerticals"
        ],
        "additionalProperties": false
      },
      "ConnectLinkTemplatePicks": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Numeric identifier of the connect-link template.",
            "example": 7
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) that owns this template.",
            "example": "acme"
          },
          "name": {
            "type": "string",
            "description": "Human-friendly name for the template, shown in the admin UI.",
            "example": "Acme onboarding"
          },
          "description": {
            "description": "Optional longer description of the template; null if unset.",
            "example": "Onboarding link for Acme Industries.",
            "type": [
              "string",
              "null"
            ]
          },
          "scopeGroupId": {
            "description": "Scope group whose scopes are requested by links from this template; null for defaults.",
            "example": 7,
            "type": [
              "number",
              "null"
            ]
          },
          "expiryDays": {
            "type": "number",
            "description": "Number of days a generated connect link remains valid before expiring.",
            "example": 7
          },
          "oneTimeOnly": {
            "type": "boolean",
            "description": "When true, links from this template are consumed after a single successful connection.",
            "example": false
          },
          "redirectUrl": {
            "description": "URL the customer is sent to after completing the connection; null to use the default.",
            "example": "https://app.acme.example/return",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "createdBy": {
            "description": "Admin user who created the template; null if created by the system.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "linkMode": {
            "type": "string",
            "const": "customer-picks-adapter",
            "description": "Picks mode: the customer chooses which of the allowed platforms/verticals to connect.",
            "example": "customer-picks-adapter"
          },
          "allowedPlatforms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AllowedPlatformOutput"
            },
            "description": "Platforms the customer may choose from.",
            "example": [
              {
                "vertical": "accounting",
                "slug": "xero"
              }
            ]
          },
          "allowedVerticals": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Verticals the customer may choose from.",
            "example": [
              "accounting"
            ]
          }
        },
        "required": [
          "id",
          "tenantId",
          "name",
          "description",
          "scopeGroupId",
          "expiryDays",
          "oneTimeOnly",
          "redirectUrl",
          "createdAt",
          "createdBy",
          "linkMode",
          "allowedPlatforms",
          "allowedVerticals"
        ],
        "additionalProperties": false
      },
      "ConnectLinkTemplateSelfRegister": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Numeric identifier of the connect-link template.",
            "example": 7
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant (operator customer) that owns this template.",
            "example": "acme"
          },
          "name": {
            "type": "string",
            "description": "Human-friendly name for the template, shown in the admin UI.",
            "example": "Acme onboarding"
          },
          "description": {
            "description": "Optional longer description of the template; null if unset.",
            "example": "Onboarding link for Acme Industries.",
            "type": [
              "string",
              "null"
            ]
          },
          "scopeGroupId": {
            "description": "Scope group whose scopes are requested by links from this template; null for defaults.",
            "example": 7,
            "type": [
              "number",
              "null"
            ]
          },
          "expiryDays": {
            "type": "number",
            "description": "Number of days a generated connect link remains valid before expiring.",
            "example": 7
          },
          "oneTimeOnly": {
            "type": "boolean",
            "description": "When true, links from this template are consumed after a single successful connection.",
            "example": false
          },
          "redirectUrl": {
            "description": "URL the customer is sent to after completing the connection; null to use the default.",
            "example": "https://app.acme.example/return",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "createdBy": {
            "description": "Admin user who created the template; null if created by the system.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "linkMode": {
            "type": "string",
            "const": "self-register",
            "description": "Self-register mode: the customer self-identifies and connects without a pre-defined platform restriction.",
            "example": "self-register"
          },
          "allowedPlatforms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AllowedPlatformOutput"
            },
            "description": "Optional platform allow-list; empty means any supported platform.",
            "example": [
              {
                "vertical": "accounting",
                "slug": "xero"
              }
            ]
          },
          "allowedVerticals": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional vertical allow-list; empty means any supported vertical.",
            "example": [
              "accounting"
            ]
          }
        },
        "required": [
          "id",
          "tenantId",
          "name",
          "description",
          "scopeGroupId",
          "expiryDays",
          "oneTimeOnly",
          "redirectUrl",
          "createdAt",
          "createdBy",
          "linkMode",
          "allowedPlatforms",
          "allowedVerticals"
        ],
        "additionalProperties": false
      },
      "TenantDomainMapEntry": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "description": "Custom domain (lower-cased, no scheme).",
            "example": "dept-a.acme.com"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant the domain resolves to.",
            "example": "acme"
          }
        },
        "required": [
          "domain",
          "tenantId"
        ],
        "additionalProperties": false,
        "description": "One domain→tenant pair from the unauthenticated resolver map."
      },
      "Tenant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable tenant identifier (slug); the value stored on `tenant_id` / `owner_tenant_id` columns.",
            "example": "acme"
          },
          "name": {
            "type": "string",
            "description": "Human-friendly tenant name shown in the admin console.",
            "example": "Acme Industries"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the tenant was registered (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the tenant was last modified (ISO 8601).",
            "example": "2026-02-01T14:20:00Z"
          }
        },
        "required": [
          "id",
          "name",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false,
        "description": "A tenant (operator customer / internal department) that data is scoped to."
      },
      "TenantDomain": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "description": "Custom domain mapped to the tenant; lower-cased, no scheme (e.g. `dept-a.acme.com`).",
            "example": "dept-a.acme.com"
          },
          "tenantId": {
            "type": "string",
            "description": "Tenant this domain resolves to.",
            "example": "acme"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the domain was attached (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          }
        },
        "required": [
          "domain",
          "tenantId",
          "createdAt"
        ],
        "additionalProperties": false,
        "description": "A custom domain → tenant mapping. Requests arriving on this host resolve to the tenant."
      },
      "DashboardDismissal": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "Task key: `conn:expired:<connectionId>`, `platform:creds:<vertical>/<platform>`, `sync:failed:<jobId>`, `refresh:failing:<connectionId>` or `wizard:<step>`.",
            "example": "conn:expired:conn_1042"
          },
          "fingerprint": {
            "type": "string",
            "description": "Fingerprint the task was cleared at (ISO 8601 for timestamps, empty when the key alone identifies the condition). The dashboard hides the task only while its live fingerprint equals this.",
            "example": "2026-09-01T00:00:00.000Z"
          },
          "by": {
            "type": "string",
            "description": "Id of the user who cleared the task.",
            "example": "usr_olivia"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the task was cleared (ISO 8601).",
            "example": "2026-09-02T09:30:00.000Z"
          }
        },
        "required": [
          "key",
          "fingerprint",
          "by",
          "createdAt"
        ],
        "additionalProperties": false,
        "description": "A dashboard task an operator cleared, and the fingerprint it was cleared at."
      },
      "RuntimeSetting": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "Dotted setting key identifying the runtime configuration value, e.g. `rateLimit.apiKey.perMinute`.",
            "example": "rateLimit.apiKey.perMinute"
          },
          "value": {
            "description": "Current value of the setting; type depends on the setting key (see `valueType`).",
            "example": 600
          },
          "valueType": {
            "description": "Type of the value: `number`, `boolean`, `string`, or `json`.",
            "example": "number",
            "$ref": "#/components/schemas/RuntimeSettingValueType"
          },
          "defaultValue": {
            "description": "Built-in default applied when no override is set.",
            "example": 300
          },
          "description": {
            "type": "string",
            "description": "Human-readable explanation of what the setting controls.",
            "example": "Maximum API-key requests allowed per minute."
          },
          "category": {
            "type": "string",
            "description": "Grouping category used to organise settings in the UI.",
            "example": "rateLimit"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the setting was last changed (ISO 8601).",
            "example": "2026-02-01T14:20:00Z"
          },
          "updatedBy": {
            "description": "Admin user who last changed the setting; null if still at default.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "isDefault": {
            "type": "boolean",
            "description": "True when the value equals the built-in default (no override has been set).",
            "example": false
          },
          "enumValues": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Closed set of legal values for a string setting, or null when it is free-form. Render it as a dropdown; the PATCH body schema enforces the same set.",
            "example": [
              "none",
              "cdn",
              "local"
            ]
          },
          "warning": {
            "description": "Confirmation text to show before saving, for a setting whose consequence is not obvious from its label. Null when the setting needs no confirmation.",
            "example": "Stores and returns the complete unmodified upstream payload for this vertical.",
            "type": [
              "string",
              "null"
            ]
          },
          "warnOn": {
            "description": "Which direction of a boolean flip the warning guards: `enable` confirms switching to true, `disable` confirms switching to false (kill switches). Null when there is no warning.",
            "example": "enable",
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "enable",
                  "disable"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "key",
          "value",
          "valueType",
          "defaultValue",
          "description",
          "category",
          "updatedAt",
          "updatedBy",
          "isDefault",
          "enumValues",
          "warning"
        ],
        "additionalProperties": false,
        "description": "A runtime-configurable setting with its current value, default, and metadata."
      },
      "RuntimeSettingValueType": {
        "type": "string",
        "enum": [
          "number",
          "boolean",
          "string",
          "json"
        ]
      },
      "LogoFetchJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Job identifier.",
            "example": "lfj_01HQ8ZKX7M2P4R6T8V0W"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "cancelling",
              "completed",
              "failed",
              "cancelled"
            ],
            "description": "Job lifecycle state.",
            "example": "running"
          },
          "force": {
            "type": "boolean",
            "description": "True when the job refetches logos that are already stored.",
            "example": false
          },
          "vertical": {
            "description": "Vertical the job is limited to, or null for all.",
            "example": "accounting",
            "type": [
              "string",
              "null"
            ]
          },
          "slug": {
            "description": "Single platform the job is limited to, or null for all.",
            "example": "xero",
            "type": [
              "string",
              "null"
            ]
          },
          "delayMs": {
            "type": "number",
            "description": "Milliseconds between Brandfetch requests for this job.",
            "example": 400
          },
          "total": {
            "type": "number",
            "description": "Platforms the job will consider.",
            "example": 1545
          },
          "progress": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/LogoFetchProgress"
              },
              {
                "type": "null"
              }
            ],
            "description": "Live counters, or null before the job starts."
          },
          "error": {
            "description": "Failure reason when the job failed.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "workerId": {
            "description": "Identifier of the replica running the job.",
            "example": "admin-api-7d9f:1:3ab91c2e",
            "type": [
              "string",
              "null"
            ]
          },
          "attempts": {
            "type": "number",
            "description": "How many times a worker has claimed this job; a crashed run is requeued.",
            "example": 1
          },
          "heartbeatAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "Last liveness ping from the owning replica (ISO 8601).",
            "example": "2026-02-01T14:20:00.000Z"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the job was queued (ISO 8601).",
            "example": "2026-02-01T14:18:00.000Z"
          },
          "createdBy": {
            "description": "Admin user who started the job.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "startedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When a worker claimed the job (ISO 8601).",
            "example": "2026-02-01T14:19:00.000Z"
          },
          "completedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the job reached a terminal state (ISO 8601).",
            "example": null
          }
        },
        "required": [
          "id",
          "status",
          "force",
          "vertical",
          "slug",
          "delayMs",
          "total",
          "progress",
          "error",
          "workerId",
          "attempts",
          "heartbeatAt",
          "createdAt",
          "createdBy",
          "startedAt",
          "completedAt"
        ],
        "additionalProperties": false,
        "description": "A background platform-logo fetch and its progress."
      },
      "LogoFetchProgress": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number",
            "description": "Platforms the job will consider in total.",
            "example": 1545
          },
          "processed": {
            "type": "number",
            "description": "Platforms handled so far.",
            "example": 902
          },
          "fetched": {
            "type": "number",
            "description": "Logos downloaded and stored.",
            "example": 840
          },
          "skipped": {
            "type": "number",
            "description": "Platforms skipped because a logo was already stored.",
            "example": 20
          },
          "notFound": {
            "type": "number",
            "description": "Platforms Brandfetch has no logo for. Not a failure — roughly 70 of the catalog have none.",
            "example": 42
          },
          "throttled": {
            "type": "number",
            "description": "Platforms abandoned to Brandfetch rate limiting. Counted separately from notFound so a later re-run picks up exactly these.",
            "example": 0
          },
          "currentSlug": {
            "description": "Platform being fetched right now.",
            "example": "xero",
            "type": [
              "string",
              "null"
            ]
          },
          "currentVertical": {
            "description": "Vertical being fetched right now.",
            "example": "accounting",
            "type": [
              "string",
              "null"
            ]
          },
          "etaMs": {
            "description": "Estimated milliseconds remaining; null until enough platforms have completed to be meaningful.",
            "example": 780000,
            "type": [
              "number",
              "null"
            ]
          },
          "byVertical": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "$ref": "#/components/schemas/LogoFetchVerticalProgress"
            },
            "description": "Progress keyed by vertical.",
            "example": {
              "accounting": {
                "total": 214,
                "processed": 180,
                "fetched": 168,
                "skipped": 4,
                "notFound": 8
              }
            }
          },
          "lastError": {
            "description": "Most recent non-fatal problem, such as a rate-limit backoff.",
            "example": "Brandfetch is rate-limiting; backing off.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "total",
          "processed",
          "fetched",
          "skipped",
          "notFound",
          "throttled",
          "currentSlug",
          "currentVertical",
          "etaMs",
          "byVertical",
          "lastError"
        ],
        "additionalProperties": false,
        "description": "Live counters for a running or finished logo fetch."
      },
      "LogoFetchVerticalProgress": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number",
            "description": "Platforms in this vertical the job will consider.",
            "example": 214
          },
          "processed": {
            "type": "number",
            "description": "Platforms in this vertical already handled.",
            "example": 180
          },
          "fetched": {
            "type": "number",
            "description": "Logos downloaded and stored for this vertical.",
            "example": 168
          },
          "skipped": {
            "type": "number",
            "description": "Platforms skipped because a logo was already stored.",
            "example": 4
          },
          "notFound": {
            "type": "number",
            "description": "Platforms Brandfetch has no logo for.",
            "example": 8
          }
        },
        "required": [
          "total",
          "processed",
          "fetched",
          "skipped",
          "notFound"
        ],
        "additionalProperties": false,
        "description": "Per-vertical breakdown of a logo fetch."
      },
      "LogoStatus": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "description": "Platforms with at least one stored logo.",
            "example": 1402
          },
          "totalBytes": {
            "type": "number",
            "description": "Total size of all stored logo bytes.",
            "example": 15728640
          },
          "lastFetchedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the newest stored logo was fetched (ISO 8601), or null when none are stored.",
            "example": "2026-02-01T14:20:00.000Z"
          }
        },
        "required": [
          "count",
          "totalBytes",
          "lastFetchedAt"
        ],
        "additionalProperties": false,
        "description": "Summary of the logos this deployment has stored."
      },
      "LogoPurgeResult": {
        "type": "object",
        "properties": {
          "deleted": {
            "type": "number",
            "description": "Number of logo rows removed.",
            "example": 1402
          }
        },
        "required": [
          "deleted"
        ],
        "additionalProperties": false
      },
      "IdentityProvider": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the identity provider (prefix `idp_`).",
            "example": "idp_northwind"
          },
          "name": {
            "type": "string",
            "description": "Human-friendly display name for the IdP.",
            "example": "Northwind SSO"
          },
          "slug": {
            "type": "string",
            "description": "URL-safe identifier used in SSO routes, e.g. `/api/sso/{slug}/...`.",
            "example": "northwind"
          },
          "protocol": {
            "description": "Authentication protocol: `saml`, `oidc`, or `ldap`.",
            "example": "oidc",
            "$ref": "#/components/schemas/IdpProtocol"
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether this IdP is active and offered as a login option.",
            "example": true
          },
          "config": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {},
            "description": "Non-secret protocol configuration; shape depends on `protocol` (secrets are never included).",
            "example": {
              "issuer": "https://idp.northwind.example",
              "clientId": "opensteward"
            }
          },
          "jitEnabled": {
            "type": "boolean",
            "description": "When true, users are just-in-time provisioned on first successful SSO login.",
            "example": true
          },
          "defaultRole": {
            "description": "Role assigned to JIT-provisioned users when no role-mapping rule matches.",
            "example": "viewer",
            "$ref": "#/components/schemas/Role"
          },
          "defaultScopeMode": {
            "description": "Scope applied when no scope rule matches: `all` tenants, or `restricted` to `defaultTenantIds`.",
            "$ref": "#/components/schemas/ScopeMode"
          },
          "defaultTenantIds": {
            "description": "Tenants granted by the default scope when it is `restricted` (empty = none).",
            "example": [],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the IdP was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the IdP was last modified (ISO 8601).",
            "example": "2026-02-01T14:20:00Z"
          },
          "createdBy": {
            "description": "Admin user who created the IdP; null if system-seeded.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "hasSecret": {
            "type": "boolean",
            "description": "Whether secret material (client secret, keys, etc.) is stored for this IdP.",
            "example": true
          }
        },
        "required": [
          "id",
          "name",
          "slug",
          "protocol",
          "enabled",
          "config",
          "jitEnabled",
          "defaultRole",
          "createdAt",
          "updatedAt",
          "createdBy",
          "hasSecret"
        ],
        "additionalProperties": {},
        "description": "A configured SSO identity provider (SAML, OIDC, or LDAP) with its non-secret config and JIT settings."
      },
      "IdpProtocol": {
        "type": "string",
        "enum": [
          "saml",
          "oidc",
          "ldap"
        ]
      },
      "RoleMappingRule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Numeric identifier of the role-mapping rule.",
            "example": 7
          },
          "providerId": {
            "type": "string",
            "description": "Identity provider this rule belongs to (prefix `idp_`).",
            "example": "idp_northwind"
          },
          "priority": {
            "type": "number",
            "description": "Evaluation order; lower numbers are checked first and the first match wins.",
            "example": 10
          },
          "claimPath": {
            "type": "string",
            "description": "Path to the IdP claim/attribute to test, e.g. `groups`.",
            "example": "groups"
          },
          "matchType": {
            "description": "How `matchValue` is compared to the claim: `equals`, `contains`, or `regex`.",
            "example": "contains",
            "$ref": "#/components/schemas/RoleMatchType"
          },
          "matchValue": {
            "type": "string",
            "description": "Value to compare against the claim using `matchType`.",
            "example": "opensteward-admins"
          },
          "role": {
            "description": "Role granted to the user when this rule matches (the base role, for a custom-role rule).",
            "example": "admin",
            "$ref": "#/components/schemas/Role"
          },
          "roleId": {
            "description": "Custom role granted when this rule matches; null when the rule grants the built-in `role`.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the rule was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          }
        },
        "required": [
          "id",
          "providerId",
          "priority",
          "claimPath",
          "matchType",
          "matchValue",
          "role",
          "createdAt"
        ],
        "additionalProperties": false,
        "description": "A rule that maps an IdP claim value to an admin role during SSO login."
      },
      "ScopeMappingRule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Numeric identifier of the scope rule.",
            "example": 3
          },
          "providerId": {
            "type": "string",
            "description": "Identity provider this rule belongs to (prefix `idp_`).",
            "example": "idp_northwind"
          },
          "priority": {
            "type": "number",
            "description": "Display order. Every matching scope rule applies — the tenants are unioned.",
            "example": 100
          },
          "claimPath": {
            "type": "string",
            "description": "Path to the IdP claim/attribute to test.",
            "example": "groups"
          },
          "matchType": {
            "description": "How `matchValue` is compared to the claim: `equals`, `contains`, or `regex`.",
            "example": "equals",
            "$ref": "#/components/schemas/RoleMatchType"
          },
          "matchValue": {
            "type": "string",
            "description": "Value to compare against the claim.",
            "example": "acme-support"
          },
          "tenantIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tenants granted when the rule matches. `[\"*\"]` grants every tenant.",
            "example": [
              "acme"
            ]
          },
          "verticals": {
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ],
            "description": "Verticals within those tenants: `*` for every vertical, or a list.",
            "example": "*"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the rule was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          }
        },
        "required": [
          "id",
          "providerId",
          "priority",
          "claimPath",
          "matchType",
          "matchValue",
          "tenantIds",
          "verticals",
          "createdAt"
        ],
        "additionalProperties": false,
        "description": "A rule that grants tenant scope to users whose IdP claim matches, re-applied on every SSO login."
      },
      "ScimToken": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the SCIM token record (prefix `scim_`).",
            "example": "scim_1042"
          },
          "providerId": {
            "type": "string",
            "description": "Identity provider this SCIM token authorizes provisioning for (prefix `idp_`).",
            "example": "idp_northwind"
          },
          "prefix": {
            "type": "string",
            "description": "Public, non-secret token prefix shown in listings; the full secret is returned only once, at creation.",
            "example": "osk_acme_8f3a"
          },
          "label": {
            "description": "Human-friendly label for the token; null if unlabeled.",
            "example": "Production key",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the token was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "createdBy": {
            "description": "Admin user who minted the token; null if system-generated.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "lastUsedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the token was last used by the IdP for SCIM provisioning; null if never used.",
            "example": "2026-02-01T14:20:00Z"
          },
          "revokedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the token was revoked; null while the token is active.",
            "example": null
          }
        },
        "required": [
          "id",
          "providerId",
          "prefix",
          "label",
          "createdAt",
          "createdBy",
          "lastUsedAt",
          "revokedAt"
        ],
        "additionalProperties": {},
        "description": "A bearer token an IdP uses to provision users/groups via the SCIM endpoints."
      },
      "ScimTokenMint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the SCIM token record (prefix `scim_`).",
            "example": "scim_1042"
          },
          "providerId": {
            "type": "string",
            "description": "Identity provider this SCIM token authorizes provisioning for (prefix `idp_`).",
            "example": "idp_northwind"
          },
          "prefix": {
            "type": "string",
            "description": "Public, non-secret token prefix shown in listings; the full secret is returned only once, at creation.",
            "example": "osk_acme_8f3a"
          },
          "label": {
            "description": "Human-friendly label for the token; null if unlabeled.",
            "example": "Production key",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the token was created (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          },
          "createdBy": {
            "description": "Admin user who minted the token; null if system-generated.",
            "example": "usr_olivia",
            "type": [
              "string",
              "null"
            ]
          },
          "lastUsedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the token was last used by the IdP for SCIM provisioning; null if never used.",
            "example": "2026-02-01T14:20:00Z"
          },
          "revokedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 date-time (e.g. 2026-04-21T22:00:00.000Z)."
              },
              {
                "type": "null"
              }
            ],
            "description": "When the token was revoked; null while the token is active.",
            "example": null
          },
          "plaintext": {
            "type": "string",
            "description": "The full plaintext SCIM token; shown only once at mint time and never retrievable again.",
            "example": "osk_acme_8f3a2b9c4d5e6f7a8b9c0d1e"
          }
        },
        "required": [
          "id",
          "providerId",
          "prefix",
          "label",
          "createdAt",
          "createdBy",
          "lastUsedAt",
          "revokedAt",
          "plaintext"
        ],
        "additionalProperties": {},
        "description": "SCIM token with the plaintext value (returned once at mint time)."
      },
      "LoginOptions": {
        "type": "object",
        "properties": {
          "providers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicIdentityProvider"
            },
            "description": "Enabled SSO providers offered as login options."
          },
          "localLoginEnabled": {
            "type": "boolean",
            "description": "Whether local username/password login is available alongside SSO.",
            "example": true
          }
        },
        "required": [
          "providers",
          "localLoginEnabled"
        ],
        "additionalProperties": false,
        "description": "Login options surfaced to the unauthenticated login screen (SSO providers and local-login flag)."
      },
      "PublicIdentityProvider": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "URL-safe identifier used to initiate SSO for this provider.",
            "example": "northwind"
          },
          "name": {
            "type": "string",
            "description": "Display name shown on the login screen.",
            "example": "Northwind SSO"
          },
          "protocol": {
            "description": "Authentication protocol used by the provider.",
            "example": "oidc",
            "$ref": "#/components/schemas/IdpProtocol"
          }
        },
        "required": [
          "slug",
          "name",
          "protocol"
        ],
        "additionalProperties": false,
        "description": "Minimal, non-sensitive IdP info exposed on the public login screen."
      },
      "SchemaStatusEntry": {
        "type": "object",
        "properties": {
          "db": {
            "type": "string",
            "description": "Logical database/namespace name.",
            "example": "accounting"
          },
          "path": {
            "type": "string",
            "description": "Filesystem path of the database file.",
            "example": "/var/lib/opensteward/accounting.db"
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SchemaMigrationRow"
            },
            "description": "Applied migration rows for this database, in version order."
          },
          "exists": {
            "type": "boolean",
            "description": "Whether the database file exists on disk.",
            "example": true
          }
        },
        "required": [
          "db",
          "path",
          "rows",
          "exists"
        ],
        "additionalProperties": false,
        "description": "Migration status for one database: its path, existence, and applied migration versions."
      },
      "SchemaMigrationRow": {
        "type": "object",
        "properties": {
          "namespace": {
            "type": "string",
            "description": "Migration namespace, typically the vertical/database the migration belongs to.",
            "example": "accounting"
          },
          "version": {
            "type": "number",
            "description": "Applied schema version number for this namespace.",
            "example": 12
          },
          "appliedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When this migration version was applied (ISO 8601).",
            "example": "2026-01-15T09:30:00Z"
          }
        },
        "required": [
          "namespace",
          "version",
          "appliedAt"
        ],
        "additionalProperties": false,
        "description": "One applied schema-migration record for a database namespace."
      },
      "LicenseStatus": {
        "type": "object",
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "VALID",
              "EXPIRING",
              "GRACE",
              "DEGRADED",
              "INVALID",
              "MISSING"
            ],
            "description": "License state. EXPIRING: within 30 days of expiry. GRACE: up to 30 days past it, everything still works. DEGRADED, INVALID, MISSING: community mode.",
            "example": "VALID"
          },
          "reason": {
            "description": "Why the state is INVALID (e.g. `BAD_SIGNATURE`, `UNKNOWN_KID`, `REVOKED`, `FILE_UNREADABLE`) or DEGRADED (`EXPIRED`).",
            "example": "BAD_SIGNATURE",
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "env",
              "file",
              "none"
            ],
            "description": "Where integration-server read the license: `OPENSTEWARD_LICENSE` (env), a file, or nowhere.",
            "example": "file"
          },
          "filePath": {
            "description": "The license file integration-server read or looked for, as a path inside its container.",
            "example": "/etc/opensteward/license/license.key",
            "type": "string"
          },
          "shadowedFile": {
            "description": "The license file integration-server is ignoring because OPENSTEWARD_LICENSE is set (the env value wins). Renewing that file changes nothing until the env value is removed.",
            "example": "/etc/opensteward/license/license.key",
            "type": "string"
          },
          "licenseId": {
            "description": "License ID.",
            "example": "lic_8f3k2a9x",
            "type": "string"
          },
          "org": {
            "description": "Organisation the license is issued to.",
            "example": "Acme Forsakring AB",
            "type": "string"
          },
          "tier": {
            "description": "Plan name, for display only: what is enabled comes from `features` and `limits`.",
            "example": "free",
            "type": "string"
          },
          "label": {
            "description": "Install label chosen when the license was issued.",
            "example": "production",
            "type": "string"
          },
          "env": {
            "description": "Licensed environment. `dev` marks a development license, which production builds refuse.",
            "example": "prod",
            "type": "string"
          },
          "kid": {
            "description": "ID of the key that signed the license.",
            "example": "k2026a",
            "type": "string"
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Enabled features: `mcp` and `vertical:<name>`.",
            "example": [
              "mcp",
              "vertical:accounting",
              "vertical:crm"
            ]
          },
          "limits": {
            "type": "object",
            "properties": {
              "connections": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991,
                "description": "Maximum connections.",
                "example": 5
              },
              "tenants": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991,
                "description": "Maximum registered tenants, counting 'default'.",
                "example": 1
              }
            },
            "required": [
              "connections",
              "tenants"
            ],
            "additionalProperties": false,
            "description": "Limits in force (the community limits outside VALID, EXPIRING and GRACE)."
          },
          "issuedAt": {
            "description": "When the license was issued.",
            "example": "2026-10-06T17:00:00.000Z",
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "description": "When the license expires.",
            "example": "2027-10-06T17:00:00.000Z",
            "type": "string",
            "format": "date-time"
          },
          "daysRemaining": {
            "description": "Whole days until expiry; negative after it.",
            "example": 362,
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "entitlementSource": {
            "type": "string",
            "enum": [
              "license",
              "community"
            ],
            "description": "`license` while the license grants what is enabled; `community` in community mode.",
            "example": "license"
          },
          "clockRollbackDetected": {
            "type": "boolean",
            "description": "True when the host clock is behind the latest time licensing has seen.",
            "example": false
          },
          "revocationList": {
            "type": "string",
            "enum": [
              "ok",
              "missing",
              "invalid"
            ],
            "description": "State of the license revocation list shipped with this build.",
            "example": "ok"
          },
          "evaluatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When integration-server last evaluated the license.",
            "example": "2026-10-09T12:00:00.000Z"
          },
          "renewalUrl": {
            "type": "string",
            "description": "Where to get or renew a license.",
            "example": "https://opensteward.dev/license"
          },
          "usage": {
            "type": "object",
            "properties": {
              "connections": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Connections integration-server holds (what `limits.connections` is checked against); null when it could not count them.",
                "example": 3
              },
              "tenants": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991,
                "description": "Tenants registered in admin-api, counting 'default' — what `limits.tenants` is checked against.",
                "example": 1
              }
            },
            "required": [
              "connections",
              "tenants"
            ],
            "additionalProperties": false,
            "description": "Usage counted against the limits."
          },
          "graceEndsAt": {
            "description": "End of the 30-day grace period after `expiresAt`; after it the deployment runs in community mode.",
            "example": "2027-11-05T17:00:00.000Z",
            "type": "string",
            "format": "date-time"
          },
          "stale": {
            "type": "boolean",
            "description": "True when integration-server is not answering and this is the last status it gave.",
            "example": false
          },
          "fetchedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When admin-api last read this status from integration-server.",
            "example": "2026-10-09T12:00:00.000Z"
          }
        },
        "required": [
          "state",
          "source",
          "features",
          "limits",
          "entitlementSource",
          "clockRollbackDetected",
          "revocationList",
          "evaluatedAt",
          "renewalUrl",
          "usage",
          "stale",
          "fetchedAt"
        ],
        "additionalProperties": false,
        "description": "The deployment's license as integration-server evaluates it, as admin-api last read it. Never contains the license token."
      },
      "DataConnectionSummary": {
        "type": "object",
        "properties": {
          "connectionId": {
            "type": "string",
            "description": "Connection id.",
            "example": "9f8e7d6c-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
          },
          "vertical": {
            "type": "string",
            "description": "Vertical.",
            "example": "crm"
          },
          "platform": {
            "type": "string",
            "description": "Platform slug.",
            "example": "hubspot"
          },
          "label": {
            "description": "Connection label.",
            "example": "Acme CRM",
            "type": [
              "string",
              "null"
            ]
          },
          "ownerTenantId": {
            "description": "Deployment tenant that owns the connection.",
            "example": "acme",
            "type": [
              "string",
              "null"
            ]
          },
          "resources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DataResourceSummary"
            },
            "description": "Stored resource types, alphabetical.",
            "example": []
          }
        },
        "required": [
          "connectionId",
          "vertical",
          "platform",
          "label",
          "ownerTenantId",
          "resources"
        ],
        "additionalProperties": false,
        "description": "What the data store holds for one connection in your scope."
      },
      "DataResourceSummary": {
        "type": "object",
        "properties": {
          "resourceType": {
            "type": "string",
            "description": "Stored resource type.",
            "example": "contacts"
          },
          "count": {
            "type": "number",
            "description": "Records stored for this connection.",
            "example": 1240
          },
          "latestChangedAt": {
            "description": "When the newest record last changed (epoch ms); null when none.",
            "example": 1767225600000,
            "type": [
              "number",
              "null"
            ]
          },
          "collectionCompletedAt": {
            "description": "When the last full sync of this type finished (epoch ms); null if never.",
            "example": 1767225600000,
            "type": [
              "number",
              "null"
            ]
          },
          "classified": {
            "type": "boolean",
            "description": "False when the type has no field classification; every field is then masked as personal data.",
            "example": true
          }
        },
        "required": [
          "resourceType",
          "count",
          "latestChangedAt",
          "collectionCompletedAt",
          "classified"
        ],
        "additionalProperties": false,
        "description": "Stored records of one type on one connection."
      },
      "DataSchema": {
        "type": "object",
        "properties": {
          "vertical": {
            "type": "string",
            "description": "Vertical.",
            "example": "crm"
          },
          "resourceType": {
            "type": "string",
            "description": "Resource type.",
            "example": "contacts"
          },
          "classified": {
            "type": "boolean",
            "description": "Whether the type is classified.",
            "example": true
          },
          "defaultClass": {
            "type": "string",
            "description": "Class of fields with no rule of their own.",
            "example": "internal"
          },
          "fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DataField"
            },
            "description": "Fields and their classes.",
            "example": []
          }
        },
        "required": [
          "vertical",
          "resourceType",
          "classified",
          "defaultClass",
          "fields"
        ],
        "additionalProperties": false,
        "description": "Fields, classes and searchability of a resource type."
      },
      "DataField": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Dotted field path.",
            "example": "email"
          },
          "class": {
            "type": "string",
            "enum": [
              "public",
              "internal",
              "pii",
              "financial",
              "secret"
            ],
            "description": "Classification of the field.",
            "example": "pii"
          },
          "mask": {
            "description": "Mask applied when hidden.",
            "example": "email",
            "type": [
              "string",
              "null"
            ]
          },
          "classified": {
            "type": "boolean",
            "description": "True when the path has its own classification entry.",
            "example": true
          },
          "inSchema": {
            "type": "boolean",
            "description": "True when the path is a top-level field of the canonical schema.",
            "example": true
          },
          "searchable": {
            "type": "boolean",
            "description": "Whether you may filter and search on this field.",
            "example": false
          }
        },
        "required": [
          "path",
          "class",
          "mask",
          "classified",
          "inSchema",
          "searchable"
        ],
        "additionalProperties": false,
        "description": "One field of a stored resource type."
      },
      "DataRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Record id.",
            "example": "cont_jane"
          },
          "resourceType": {
            "type": "string",
            "description": "Resource type.",
            "example": "contacts"
          },
          "vertical": {
            "type": "string",
            "description": "Vertical.",
            "example": "crm"
          },
          "platform": {
            "type": "string",
            "description": "Platform slug.",
            "example": "hubspot"
          },
          "connectionId": {
            "type": "string",
            "description": "Connection id.",
            "example": "9f8e7d6c-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
          },
          "fetchedAt": {
            "description": "When the record was fetched (ISO 8601).",
            "example": "2026-03-01T10:00:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "description": "When the stored row was last written (ISO 8601).",
            "example": "2026-03-01T10:00:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "changedAt": {
            "description": "When the record content last changed (ISO 8601).",
            "example": "2026-03-01T10:00:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "normVersion": {
            "description": "Normaliser version that wrote the record.",
            "example": "1",
            "type": [
              "string",
              "null"
            ]
          },
          "data": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {},
            "description": "The canonical record, masked by field classification: personal data masked unless revealed, secrets removed.",
            "example": {
              "id": "cont_jane",
              "email": "j***@acme.example",
              "title": "CFO"
            }
          }
        },
        "required": [
          "id",
          "resourceType",
          "vertical",
          "platform",
          "connectionId",
          "fetchedAt",
          "updatedAt",
          "changedAt",
          "normVersion",
          "data"
        ],
        "additionalProperties": false,
        "description": "One stored record, masked for the caller."
      },
      "DataRecordPageMeta": {
        "type": "object",
        "properties": {
          "piiRevealed": {
            "type": "boolean",
            "description": "Personal data is unmasked.",
            "example": false
          },
          "financialMasked": {
            "type": "boolean",
            "description": "Financial fields are masked.",
            "example": false
          },
          "classified": {
            "type": "boolean",
            "description": "The type is classified.",
            "example": true
          },
          "nextCursor": {
            "description": "Opaque cursor for the next page; null on the last.",
            "example": "eyJ2IjoxfQ",
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "type": "number",
            "description": "Matching records (capped).",
            "example": 1240
          },
          "totalCapped": {
            "type": "boolean",
            "description": "True when `total` hit the count cap (10,000).",
            "example": false
          }
        },
        "required": [
          "piiRevealed",
          "financialMasked",
          "classified",
          "nextCursor",
          "total",
          "totalCapped"
        ],
        "additionalProperties": false,
        "description": "Pagination and masking of a record page."
      },
      "DataRecordMeta": {
        "type": "object",
        "properties": {
          "piiRevealed": {
            "type": "boolean",
            "description": "Personal data is unmasked.",
            "example": false
          },
          "financialMasked": {
            "type": "boolean",
            "description": "Financial fields are masked.",
            "example": false
          },
          "classified": {
            "type": "boolean",
            "description": "The type is classified.",
            "example": true
          }
        },
        "required": [
          "piiRevealed",
          "financialMasked",
          "classified"
        ],
        "additionalProperties": false,
        "description": "How a stored record was masked."
      },
      "Dashboard": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Dashboard id: `builtin:<slug>` or `dsh_…`.",
            "example": "builtin:ecommerce"
          },
          "name": {
            "type": "string",
            "description": "Dashboard name.",
            "example": "Ecommerce"
          },
          "description": {
            "description": "What the dashboard is for.",
            "example": "Orders and revenue.",
            "type": [
              "string",
              "null"
            ]
          },
          "widgets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DashboardWidgetOutput"
            },
            "description": "Widgets, in display order.",
            "example": []
          },
          "builtin": {
            "type": "boolean",
            "description": "Defined in code; read-only.",
            "example": true
          },
          "vertical": {
            "description": "The vertical a built-in dashboard is about; null otherwise.",
            "example": "ecommerce",
            "type": [
              "string",
              "null"
            ]
          },
          "ownerUserId": {
            "description": "Owner; null for a built-in.",
            "example": "usr_1",
            "type": [
              "string",
              "null"
            ]
          },
          "audience": {
            "$ref": "#/components/schemas/DashboardAudienceView"
          },
          "pinnedTenants": {
            "$ref": "#/components/schemas/DashboardPinnedTenantsView"
          },
          "editable": {
            "type": "boolean",
            "description": "Whether you may edit or delete it.",
            "example": false
          },
          "createdAt": {
            "description": "ISO 8601; null for a built-in.",
            "example": "2026-03-01T10:00:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "description": "ISO 8601; null for a built-in.",
            "example": "2026-03-01T10:00:00.000Z",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "widgets",
          "builtin",
          "vertical",
          "ownerUserId",
          "audience",
          "pinnedTenants",
          "editable",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false,
        "description": "A native dashboard."
      },
      "DashboardAudienceView": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "private",
              "tenants",
              "everyone"
            ],
            "description": "`private` (only the owner), `tenants` or `everyone`.",
            "example": "tenants"
          },
          "tenants": {
            "description": "For `tenants`: who it is shared with (limited to your own access unless you may edit it).",
            "example": [
              "acme"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "kind"
        ],
        "additionalProperties": false,
        "description": "Who can see a dashboard, as returned by the API.",
        "example": {
          "kind": "tenants",
          "tenants": [
            "acme"
          ]
        }
      },
      "DashboardPinnedTenantsView": {
        "anyOf": [
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "null"
          }
        ],
        "description": "Tenants the data is limited to; `null` = every tenant the viewer can see.",
        "example": [
          "acme"
        ]
      },
      "MetricInfo": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Metric id.",
            "example": "ecommerce.orders_per_day"
          },
          "title": {
            "type": "string",
            "description": "Title.",
            "example": "Orders per day"
          },
          "description": {
            "type": "string",
            "description": "What it measures.",
            "example": "Orders created per day."
          },
          "kind": {
            "type": "string",
            "enum": [
              "value",
              "timeseries",
              "breakdown",
              "ratio",
              "duration",
              "aging",
              "concentration",
              "matrix",
              "histogram",
              "composition",
              "dso",
              "dpo",
              "ccc",
              "table"
            ],
            "description": "Shape of the result.",
            "example": "timeseries"
          },
          "unit": {
            "type": "string",
            "enum": [
              "count",
              "money",
              "percent",
              "days",
              "hours",
              "index",
              "quantity"
            ],
            "description": "Unit of the headline value (`percent` is 0–100).",
            "example": "count"
          },
          "section": {
            "type": "string",
            "enum": [
              "overview",
              "sales",
              "receivables",
              "payables",
              "cash",
              "tax",
              "profitability",
              "customers",
              "products",
              "fulfillment",
              "subscriptions",
              "pipeline",
              "performance",
              "activity",
              "workload",
              "quality",
              "speed",
              "satisfaction",
              "delivery",
              "cost",
              "stock",
              "purchasing",
              "risk",
              "system"
            ],
            "description": "Where the metric sits inside its vertical, for grouping in the editor.",
            "example": "sales"
          },
          "vertical": {
            "description": "Vertical; null for system metrics.",
            "example": "ecommerce",
            "type": [
              "string",
              "null"
            ]
          },
          "resourceType": {
            "description": "Resource type; null for system metrics.",
            "example": "orders",
            "type": [
              "string",
              "null"
            ]
          },
          "charts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DashboardChart"
            },
            "description": "Chart types that fit this metric; the first is the default.",
            "example": [
              "line",
              "area",
              "bar"
            ]
          },
          "money": {
            "type": "boolean",
            "description": "Values are money, one set per currency, never combined across currencies.",
            "example": false
          },
          "currencyAware": {
            "type": "boolean",
            "description": "The `currency` parameter changes the result.",
            "example": false
          },
          "snapshot": {
            "type": "boolean",
            "description": "Evaluated as of now: the range is ignored.",
            "example": false
          },
          "granular": {
            "type": "boolean",
            "description": "The `granularity` parameter applies (a series over time).",
            "example": true
          },
          "comparable": {
            "type": "boolean",
            "description": "`compare=1` adds `previous`, the prior equal-length range.",
            "example": true
          },
          "defaultGranularity": {
            "description": "The bucket size this metric uses when a request leaves `granularity` unset (or `auto`); absent means the range decides.",
            "example": "month",
            "type": "string",
            "enum": [
              "day",
              "week",
              "month"
            ]
          },
          "thresholds": {
            "$ref": "#/components/schemas/MetricThresholds"
          },
          "note": {
            "description": "A caveat to show under the widget.",
            "example": "Proxy: updatedAt as completion date.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "title",
          "description",
          "kind",
          "unit",
          "section",
          "vertical",
          "resourceType",
          "charts",
          "money",
          "currencyAware",
          "snapshot",
          "granular",
          "comparable"
        ],
        "additionalProperties": false,
        "description": "One metric in the catalog."
      },
      "MetricThresholds": {
        "type": "object",
        "properties": {
          "warn": {
            "type": "number",
            "description": "Warning level.",
            "example": 20
          },
          "crit": {
            "type": "number",
            "description": "Critical level.",
            "example": 40
          },
          "direction": {
            "type": "string",
            "enum": [
              "above",
              "below"
            ],
            "description": "`above`: higher is worse; `below`: lower is worse.",
            "example": "above"
          }
        },
        "required": [
          "warn",
          "crit",
          "direction"
        ],
        "additionalProperties": false,
        "description": "Levels that colour a number or gauge chart, in the metric’s unit."
      },
      "MetricResult": {
        "type": "object",
        "properties": {
          "metric": {
            "$ref": "#/components/schemas/MetricInfo"
          },
          "range": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "description": "First day, inclusive.",
                "example": "2026-03-01"
              },
              "to": {
                "type": "string",
                "description": "Last day, inclusive.",
                "example": "2026-03-30"
              }
            },
            "required": [
              "from",
              "to"
            ],
            "additionalProperties": false,
            "description": "Days covered.",
            "example": {
              "from": "2026-03-01",
              "to": "2026-03-30"
            }
          },
          "granularity": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "day",
                  "week",
                  "month"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Bucket size of a series over time; null for other kinds.",
            "example": "day"
          },
          "currency": {
            "description": "The currency filter applied; null means every currency, each separately.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "currencies": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Currencies present in scope and range before the filter ([] for currency-free metrics).",
            "example": [
              "EUR",
              "USD"
            ]
          },
          "value": {
            "description": "Headline for currency-free metrics (count, percent, days, index); null for money, and for a result that spans several currencies.",
            "example": 120,
            "type": [
              "number",
              "null"
            ]
          },
          "previous": {
            "description": "With `compare=1`: the same metric over the prior equal-length range.",
            "example": {
              "value": 98,
              "range": {
                "from": "2026-01-30",
                "to": "2026-02-28"
              }
            },
            "type": "object",
            "properties": {
              "value": {
                "description": "Headline over the prior range.",
                "example": 98,
                "type": [
                  "number",
                  "null"
                ]
              },
              "totals": {
                "description": "Money headlines over the prior range, one per currency.",
                "example": [],
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MetricTotal"
                }
              },
              "range": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string",
                    "description": "First day, inclusive.",
                    "example": "2026-03-01"
                  },
                  "to": {
                    "type": "string",
                    "description": "Last day, inclusive.",
                    "example": "2026-03-30"
                  }
                },
                "required": [
                  "from",
                  "to"
                ],
                "additionalProperties": false,
                "description": "Days covered.",
                "example": {
                  "from": "2026-03-01",
                  "to": "2026-03-30"
                }
              }
            },
            "required": [
              "value",
              "range"
            ],
            "additionalProperties": false
          },
          "totals": {
            "description": "Money headlines, one per currency.",
            "example": [],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MetricTotal"
            }
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MetricSeries"
            },
            "description": "Series to chart; money series always carry `currency`.",
            "example": []
          },
          "kpis": {
            "description": "Named numbers.",
            "example": [],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MetricKpi"
            }
          },
          "table": {
            "description": "Rows of the result: top-N with share and cumulative share, stats, lists.",
            "example": {
              "columns": [],
              "rows": []
            },
            "type": "object",
            "properties": {
              "columns": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "key",
                    "label"
                  ],
                  "additionalProperties": false
                }
              },
              "rows": {
                "type": "array",
                "items": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": [
                      "string",
                      "number",
                      "null"
                    ]
                  }
                }
              }
            },
            "required": [
              "columns",
              "rows"
            ],
            "additionalProperties": false
          },
          "matrix": {
            "description": "Heatmap cells (matrix kind).",
            "example": {
              "x": [
                "Mon"
              ],
              "y": [
                "09:00 UTC"
              ],
              "cells": [
                [
                  0,
                  0,
                  3
                ]
              ]
            },
            "type": "object",
            "properties": {
              "x": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "y": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "cells": {
                "type": "array",
                "items": {
                  "minItems": 3,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                "description": "`[xIndex, yIndex, value]`, every cell present.",
                "example": [
                  [
                    0,
                    0,
                    3
                  ]
                ]
              }
            },
            "required": [
              "x",
              "y",
              "cells"
            ],
            "additionalProperties": false
          },
          "stats": {
            "description": "Distributions: `All` first, then one per group.",
            "example": [],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MetricStats"
            }
          },
          "coverage": {
            "description": "How many records the metric could use.",
            "example": {
              "eligible": 62,
              "total": 100
            },
            "type": "object",
            "properties": {
              "eligible": {
                "type": "number",
                "description": "Records carrying every coverage field.",
                "example": 62
              },
              "total": {
                "type": "number",
                "description": "Records in scope and range.",
                "example": 100
              }
            },
            "required": [
              "eligible",
              "total"
            ],
            "additionalProperties": false
          },
          "thresholds": {
            "$ref": "#/components/schemas/MetricThresholds"
          },
          "note": {
            "description": "A caveat to show under the widget.",
            "example": "Weekday and hour are UTC.",
            "type": "string"
          },
          "masked": {
            "type": "boolean",
            "description": "True when financial values are withheld by `data_access.mask_financial`.",
            "example": false
          },
          "filter": {
            "description": "The connection / adapter filter applied, when `connection` or `platform` was given; absent otherwise.",
            "example": {
              "connection": null,
              "platform": "shopify",
              "vertical": "ecommerce"
            },
            "type": "object",
            "properties": {
              "connection": {
                "description": "The connection the result is narrowed to; null for every connection.",
                "example": "0b6f3c1e-8a2d-4c55-9e0f-3d1f2a7b9c10",
                "type": [
                  "string",
                  "null"
                ]
              },
              "platform": {
                "description": "The adapter the result is narrowed to; null for every adapter.",
                "example": "shopify",
                "type": [
                  "string",
                  "null"
                ]
              },
              "vertical": {
                "description": "The vertical the filter was kept to; null when the request named none.",
                "example": "ecommerce",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "connection",
              "platform",
              "vertical"
            ],
            "additionalProperties": false
          },
          "generatedAt": {
            "type": "string",
            "description": "When the values were computed (cached up to 60 s).",
            "example": "2026-03-30T10:00:00.000Z"
          }
        },
        "required": [
          "metric",
          "range",
          "granularity",
          "currency",
          "currencies",
          "value",
          "series",
          "masked",
          "generatedAt"
        ],
        "additionalProperties": false,
        "description": "A metric computed over your scope."
      },
      "MetricTotal": {
        "type": "object",
        "properties": {
          "currency": {
            "description": "Currency; null when the records carried none.",
            "example": "USD",
            "type": [
              "string",
              "null"
            ]
          },
          "amount": {
            "type": "number",
            "description": "Amount in major units.",
            "example": 19.99
          },
          "amountMinor": {
            "type": "number",
            "description": "Amount in minor units.",
            "example": 1999
          }
        },
        "required": [
          "currency",
          "amount",
          "amountMinor"
        ],
        "additionalProperties": false,
        "description": "A money headline for one currency."
      },
      "MetricSeries": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Series name.",
            "example": "USD"
          },
          "currency": {
            "description": "ISO 4217 code of a money series; null when its records carried none. Absent on counts. A series never mixes currencies.",
            "example": "USD",
            "type": [
              "string",
              "null"
            ]
          },
          "kind": {
            "description": "How a `combo` chart draws this series.",
            "example": "bar",
            "type": "string",
            "enum": [
              "bar",
              "line"
            ]
          },
          "points": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MetricPoint"
            },
            "description": "Points.",
            "example": []
          }
        },
        "required": [
          "name",
          "points"
        ],
        "additionalProperties": false,
        "description": "One series of a metric result."
      },
      "MetricPoint": {
        "type": "object",
        "properties": {
          "x": {
            "type": "string",
            "description": "Bucket (`YYYY-MM-DD`, `YYYY-Www`, `YYYY-MM`) or category.",
            "example": "2026-03-01"
          },
          "y": {
            "description": "Value (money in major units); null for a bucket with no defined value (a ratio with no denominator, an average of nothing).",
            "example": 42,
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "x",
          "y"
        ],
        "additionalProperties": false,
        "description": "One point of a series."
      },
      "MetricKpi": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "Stable key (`p50`, `hhi`, `top5_share`, `numerator`, …).",
            "example": "p50"
          },
          "label": {
            "type": "string",
            "description": "Display label.",
            "example": "Median"
          },
          "value": {
            "description": "Value; null when undefined.",
            "example": 3.5,
            "type": [
              "number",
              "null"
            ]
          },
          "unit": {
            "type": "string",
            "enum": [
              "count",
              "money",
              "percent",
              "days",
              "hours",
              "index",
              "quantity"
            ],
            "description": "Unit of the value.",
            "example": "days"
          },
          "currency": {
            "description": "Currency of a per-currency KPI; absent on currency-free ones.",
            "example": "USD",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "key",
          "label",
          "value",
          "unit"
        ],
        "additionalProperties": false,
        "description": "A named number of a metric result."
      },
      "MetricStats": {
        "type": "object",
        "properties": {
          "group": {
            "type": "string",
            "description": "Group label; the first entry is `All`.",
            "example": "All"
          },
          "n": {
            "type": "number",
            "description": "Values in the group.",
            "example": 12
          },
          "min": {
            "type": "number",
            "description": "Minimum.",
            "example": 0.5
          },
          "p25": {
            "type": "number",
            "description": "25th percentile.",
            "example": 1
          },
          "p50": {
            "type": "number",
            "description": "Median.",
            "example": 2
          },
          "p75": {
            "type": "number",
            "description": "75th percentile.",
            "example": 4
          },
          "p90": {
            "type": "number",
            "description": "90th percentile.",
            "example": 7
          },
          "max": {
            "type": "number",
            "description": "Maximum.",
            "example": 12
          },
          "mean": {
            "type": "number",
            "description": "Mean.",
            "example": 3.1
          }
        },
        "required": [
          "group",
          "n",
          "min",
          "p25",
          "p50",
          "p75",
          "p90",
          "max",
          "mean"
        ],
        "additionalProperties": false,
        "description": "The distribution of one group (a boxplot)."
      },
      "DashboardConnections": {
        "type": "object",
        "properties": {
          "connections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DashboardConnection"
            },
            "description": "Matching connections, at most `limit`: an exact id match first, then by label (unlabelled last), then id.",
            "example": []
          },
          "platforms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DashboardConnectionPlatform"
            },
            "description": "The adapters among the vertical’s connections you can see (ignoring `search` and `platform`), by slug.",
            "example": [
              {
                "slug": "shopify",
                "name": "Shopify",
                "count": 3
              }
            ]
          },
          "total": {
            "type": "number",
            "description": "How many connections match, before `limit`.",
            "example": 3
          }
        },
        "required": [
          "connections",
          "platforms",
          "total"
        ],
        "additionalProperties": false,
        "description": "What a dashboard’s connection filter offers."
      },
      "DashboardConnection": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Connection id: the value of a metric’s `connection` parameter.",
            "example": "0b6f3c1e-8a2d-4c55-9e0f-3d1f2a7b9c10"
          },
          "label": {
            "description": "The name the operator gave the connection; null when it has none.",
            "example": "Acme main shop",
            "type": [
              "string",
              "null"
            ]
          },
          "platform": {
            "type": "string",
            "description": "Adapter slug.",
            "example": "shopify"
          },
          "vertical": {
            "type": "string",
            "description": "Vertical.",
            "example": "ecommerce"
          }
        },
        "required": [
          "id",
          "label",
          "platform",
          "vertical"
        ],
        "additionalProperties": false,
        "description": "A connection a dashboard can be filtered to. Carries no tenant, status or credential."
      },
      "DashboardConnectionPlatform": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Adapter slug.",
            "example": "shopify"
          },
          "name": {
            "type": "string",
            "description": "Display name from the platform catalog; the slug when the catalog has none.",
            "example": "Shopify"
          },
          "count": {
            "type": "number",
            "description": "Connections of this adapter you can see.",
            "example": 3
          }
        },
        "required": [
          "slug",
          "name",
          "count"
        ],
        "additionalProperties": false,
        "description": "An adapter a dashboard can be filtered to."
      },
      "SupersetStatus": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "True when admin-api is configured with a Superset URL.",
            "example": true
          },
          "publicUrl": {
            "description": "Browser-facing Superset URL the admin UI embeds from; null when disabled.",
            "example": "https://superset.example.com",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "enabled",
          "publicUrl"
        ],
        "additionalProperties": false,
        "description": "Whether embedded Superset dashboards are available."
      },
      "SupersetDashboard": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Registry id.",
            "example": "ssd_0123456789abcdef0123"
          },
          "title": {
            "type": "string",
            "description": "Title.",
            "example": "Connection data overview"
          },
          "description": {
            "description": "What the dashboard shows.",
            "example": "Records per vertical and the connections behind them.",
            "type": [
              "string",
              "null"
            ]
          },
          "embeddedUuid": {
            "type": "string",
            "description": "Id of the dashboard’s embedded configuration in Superset.",
            "example": "6c0a4bd6-3f7c-4c5e-9d52-7b1f0e0f2a11"
          },
          "verticals": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Verticals it is about; null when not tied to one.",
            "example": null
          },
          "requiredPermission": {
            "description": "Permission needed on top of `dashboards:view`; null when none.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "audience": {
            "$ref": "#/components/schemas/DashboardAudienceView"
          },
          "pinnedTenants": {
            "$ref": "#/components/schemas/DashboardPinnedTenantsView"
          },
          "updatedAt": {
            "type": "string",
            "description": "When the registry entry last changed (ISO 8601).",
            "example": "2026-09-01T10:00:00.000Z"
          }
        },
        "required": [
          "id",
          "title",
          "description",
          "embeddedUuid",
          "verticals",
          "requiredPermission",
          "audience",
          "pinnedTenants",
          "updatedAt"
        ],
        "additionalProperties": false,
        "description": "An embeddable Superset dashboard."
      },
      "SupersetGuestToken": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "description": "The guest token (a JWT signed by Superset).",
            "example": "eyJ…"
          },
          "expiresAt": {
            "description": "When the token expires (ISO 8601), when Superset says.",
            "example": "2026-09-01T10:05:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "embeddedUuid": {
            "type": "string",
            "description": "Embedded configuration id to pass to the embedded SDK.",
            "example": "6c0a4bd6-3f7c-4c5e-9d52-7b1f0e0f2a11"
          },
          "supersetDomain": {
            "type": "string",
            "description": "Browser-facing Superset URL.",
            "example": "https://superset.example.com"
          },
          "restricted": {
            "type": "boolean",
            "description": "True when the token carries a tenant row-level-security clause.",
            "example": false
          }
        },
        "required": [
          "token",
          "expiresAt",
          "embeddedUuid",
          "supersetDomain",
          "restricted"
        ],
        "additionalProperties": false,
        "description": "A short-lived Superset guest token."
      },
      "DestinationTypeInfo": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Type id.",
            "example": "s3"
          },
          "label": {
            "type": "string",
            "description": "Display name.",
            "example": "Amazon S3 (and S3-compatible)"
          },
          "kind": {
            "type": "string",
            "description": "`object_store` (Parquet files), `table` (rows in a database) or `loader`.",
            "example": "object_store"
          },
          "available": {
            "type": "boolean",
            "description": "False for reserved types that cannot be created yet.",
            "example": true
          },
          "experimental": {
            "description": "True for types whose behaviour may still change.",
            "example": false,
            "type": "boolean"
          },
          "configSchema": {
            "anyOf": [
              {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {}
              },
              {
                "type": "null"
              }
            ],
            "description": "JSON Schema of the non-secret settings.",
            "example": {
              "type": "object",
              "properties": {
                "bucket": {
                  "type": "string"
                }
              }
            }
          },
          "secretsSchema": {
            "anyOf": [
              {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {}
              },
              {
                "type": "null"
              }
            ],
            "description": "JSON Schema of the write-only credential fields.",
            "example": {
              "type": "object",
              "properties": {
                "secretAccessKey": {
                  "type": "string"
                }
              }
            }
          },
          "secretFields": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of the write-only fields.",
            "example": [
              "accessKeyId",
              "secretAccessKey",
              "sessionToken"
            ]
          }
        },
        "required": [
          "type",
          "label",
          "kind",
          "available",
          "configSchema",
          "secretsSchema",
          "secretFields"
        ],
        "additionalProperties": false,
        "description": "One destination type and its settings form."
      },
      "Destination": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Destination id.",
            "example": "5b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b"
          },
          "name": {
            "type": "string",
            "description": "Display name.",
            "example": "Lake (prod)"
          },
          "type": {
            "type": "string",
            "description": "Destination type, one of the ids in the type catalog (e.g. `s3`, `postgres`).",
            "example": "s3"
          },
          "config": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {},
            "description": "Non-secret settings, as validated for the type.",
            "example": {
              "bucket": "lake",
              "region": "eu-west-1",
              "prefix": "opensteward/"
            }
          },
          "secretFieldsSet": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of the credential fields that hold a value. Values are never returned.",
            "example": [
              "accessKeyId",
              "secretAccessKey"
            ]
          },
          "includePii": {
            "type": "boolean",
            "description": "True when personal data is exported unmasked.",
            "example": false
          },
          "piiApprovedBy": {
            "description": "User id that approved exporting personal data; null when masked.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "scope": {
            "$ref": "#/components/schemas/DestinationScopeOutput"
          },
          "intervalSec": {
            "type": "number",
            "description": "Seconds between runs.",
            "example": 3600
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether scheduled runs happen.",
            "example": true
          },
          "createdBy": {
            "description": "User id that created the destination.",
            "example": "b3c4d5e6-0000-4000-8000-000000000001",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "description": "When the destination was created (ISO 8601).",
            "example": "2026-09-29T12:00:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "description": "When the destination last changed (ISO 8601).",
            "example": "2026-09-29T12:00:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "lastRunAt": {
            "description": "When the last run started (ISO 8601); null if never.",
            "example": "2026-09-29T13:00:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "lastStatus": {
            "description": "Status of the last run: `running`, `success` or `failed`; null if never run.",
            "example": "success",
            "type": [
              "string",
              "null"
            ]
          },
          "lastError": {
            "description": "Error of the last failed run.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "config",
          "secretFieldsSet",
          "includePii",
          "piiApprovedBy",
          "scope",
          "intervalSec",
          "enabled",
          "createdBy",
          "createdAt",
          "updatedAt",
          "lastRunAt",
          "lastStatus",
          "lastError"
        ],
        "additionalProperties": false,
        "description": "A warehouse or lake destination. Never carries secrets."
      },
      "DestinationTestResult": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "description": "Whether the test passed.",
            "example": true
          },
          "error": {
            "description": "Why it failed.",
            "example": "AccessDenied: Access Denied",
            "type": "string"
          },
          "latencyMs": {
            "type": "number",
            "description": "How long the test took.",
            "example": 412
          }
        },
        "required": [
          "ok",
          "latencyMs"
        ],
        "additionalProperties": false,
        "description": "Outcome of a destination connection test."
      },
      "DestinationRunStarted": {
        "type": "object",
        "properties": {
          "runId": {
            "type": "string",
            "description": "Id of the run started.",
            "example": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
          }
        },
        "required": [
          "runId"
        ],
        "additionalProperties": false,
        "description": "A run that was started."
      },
      "DestinationBackfillResult": {
        "type": "object",
        "properties": {
          "cursorsReset": {
            "type": "number",
            "description": "Cursors reset.",
            "example": 3
          },
          "runId": {
            "description": "Run started; null when none was (disabled, or one is already running).",
            "example": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "cursorsReset",
          "runId"
        ],
        "additionalProperties": false,
        "description": "Outcome of a backfill."
      },
      "DestinationRun": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Run id.",
            "example": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
          },
          "destinationId": {
            "type": "string",
            "description": "Destination id.",
            "example": "5b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b"
          },
          "trigger": {
            "type": "string",
            "description": "What started it: `schedule`, `manual` or `backfill`.",
            "example": "schedule"
          },
          "status": {
            "type": "string",
            "description": "`running`, `success` or `failed`.",
            "example": "success"
          },
          "startedAt": {
            "description": "Start time (ISO 8601).",
            "example": "2026-09-29T12:00:00.000Z",
            "type": [
              "string",
              "null"
            ]
          },
          "finishedAt": {
            "description": "End time (ISO 8601); null while running.",
            "example": "2026-09-29T12:00:04.210Z",
            "type": [
              "string",
              "null"
            ]
          },
          "rowsWritten": {
            "type": "number",
            "description": "Rows exported.",
            "example": 1250
          },
          "deletesWritten": {
            "type": "number",
            "description": "Deletions exported.",
            "example": 3
          },
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DestinationRunFile"
            },
            "description": "Files written.",
            "example": []
          },
          "error": {
            "description": "Why it failed.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "destinationId",
          "trigger",
          "status",
          "startedAt",
          "finishedAt",
          "rowsWritten",
          "deletesWritten",
          "files",
          "error"
        ],
        "additionalProperties": false,
        "description": "One export run of a destination."
      },
      "DestinationRunFile": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path relative to the destination prefix (object stores) or the table name.",
            "example": "vertical=crm/resource_type=contacts/dt=2026-09-29/5b1c-00000.parquet"
          },
          "kind": {
            "type": "string",
            "description": "`rows`, `deletes`, `manifest` or `table`.",
            "example": "rows"
          },
          "vertical": {
            "description": "Vertical.",
            "example": "crm",
            "type": "string"
          },
          "resourceType": {
            "description": "Resource type.",
            "example": "contacts",
            "type": "string"
          },
          "rows": {
            "type": "number",
            "description": "Rows written.",
            "example": 1250
          }
        },
        "required": [
          "path",
          "kind",
          "rows"
        ],
        "additionalProperties": false,
        "description": "A file (or table batch) a run wrote."
      },
      "SqlAccessStatus": {
        "type": "object",
        "properties": {
          "backend": {
            "type": "string",
            "enum": [
              "postgres",
              "sqlite"
            ],
            "description": "Database backend. SQL access needs `postgres`.",
            "example": "postgres"
          },
          "mode": {
            "type": "string",
            "enum": [
              "managed",
              "manual"
            ],
            "description": "`managed` when `ANALYTICS_ADMIN_DATABASE_URL` is set (OpenSteward creates roles and views itself); `manual` when an operator runs the provisioning script.",
            "example": "managed"
          },
          "provisioned": {
            "type": "boolean",
            "description": "Views are deployed.",
            "example": true
          },
          "version": {
            "description": "Deployed catalog version; null when not provisioned.",
            "example": 1,
            "type": [
              "number",
              "null"
            ]
          },
          "hash": {
            "description": "Hash of the deployed catalog.",
            "example": "9d2f…",
            "type": [
              "string",
              "null"
            ]
          },
          "catalogHash": {
            "type": "string",
            "description": "Hash of this build's catalog.",
            "example": "9d2f…"
          },
          "upToDate": {
            "type": "boolean",
            "description": "The deployed views match this build's catalog.",
            "example": true
          },
          "readHost": {
            "description": "Host BI tools should connect to (`ANALYTICS_READ_HOST`), often a replica.",
            "example": "replica.internal",
            "type": [
              "string",
              "null"
            ]
          },
          "database": {
            "description": "Postgres database name.",
            "example": "opensteward",
            "type": [
              "string",
              "null"
            ]
          },
          "schemas": {
            "type": "object",
            "properties": {
              "masked": {
                "type": "string",
                "description": "Masked schema.",
                "example": "os_analytics"
              },
              "pii": {
                "type": "string",
                "description": "Unmasked schema.",
                "example": "os_analytics_pii"
              }
            },
            "required": [
              "masked",
              "pii"
            ],
            "additionalProperties": false,
            "description": "Stable schema names.",
            "example": {
              "masked": "os_analytics",
              "pii": "os_analytics_pii"
            }
          },
          "pgcrypto": {
            "description": "Whether pgcrypto is installed (hmac masks need it).",
            "example": true,
            "type": [
              "boolean",
              "null"
            ]
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Deployment problems worth fixing.",
            "example": []
          }
        },
        "required": [
          "backend",
          "mode",
          "provisioned",
          "version",
          "hash",
          "catalogHash",
          "upToDate",
          "readHost",
          "database",
          "schemas",
          "pgcrypto",
          "warnings"
        ],
        "additionalProperties": false,
        "description": "State of read-only SQL access on this deployment."
      },
      "SqlAccessProvisionResult": {
        "type": "object",
        "properties": {
          "changed": {
            "type": "boolean",
            "description": "Whether anything was (re)created.",
            "example": true
          },
          "version": {
            "type": "number",
            "description": "Catalog version now deployed.",
            "example": 1
          },
          "hash": {
            "type": "string",
            "description": "Deployed catalog hash.",
            "example": "9d2f…"
          },
          "breaking": {
            "type": "boolean",
            "description": "A new version was cut because a view or column was removed or retyped.",
            "example": false
          },
          "changes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What changed, one line each.",
            "example": []
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Deployment warnings.",
            "example": []
          }
        },
        "required": [
          "changed",
          "version",
          "hash",
          "breaking",
          "changes",
          "warnings"
        ],
        "additionalProperties": false,
        "description": "Outcome of provisioning the SQL views."
      },
      "SqlAccessCatalog": {
        "type": "object",
        "properties": {
          "format": {
            "type": "number",
            "description": "Catalog format.",
            "example": 1
          },
          "hash": {
            "type": "string",
            "description": "Catalog hash.",
            "example": "9d2f…"
          },
          "schemas": {
            "type": "object",
            "properties": {
              "masked": {
                "type": "string",
                "description": "Masked schema.",
                "example": "os_analytics"
              },
              "pii": {
                "type": "string",
                "description": "Unmasked schema.",
                "example": "os_analytics_pii"
              }
            },
            "required": [
              "masked",
              "pii"
            ],
            "additionalProperties": false,
            "description": "Stable schema names.",
            "example": {
              "masked": "os_analytics",
              "pii": "os_analytics_pii"
            }
          },
          "views": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SqlAccessCatalogView"
            },
            "description": "Views in your scope.",
            "example": []
          }
        },
        "required": [
          "format",
          "hash",
          "schemas",
          "views"
        ],
        "additionalProperties": false,
        "description": "The SQL views and their columns."
      },
      "SqlAccessCatalogView": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "View name.",
            "example": "crm_contacts"
          },
          "kind": {
            "type": "string",
            "description": "`resource` or `system`.",
            "example": "resource"
          },
          "vertical": {
            "description": "Vertical.",
            "example": "crm",
            "type": "string"
          },
          "resourceType": {
            "description": "Resource type.",
            "example": "contacts",
            "type": "string"
          },
          "columns": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SqlAccessCatalogColumn"
            },
            "description": "Columns in order.",
            "example": []
          }
        },
        "required": [
          "name",
          "kind",
          "columns"
        ],
        "additionalProperties": false,
        "description": "One SQL view."
      },
      "SqlAccessCatalogColumn": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Column name.",
            "example": "email"
          },
          "source": {
            "type": "string",
            "description": "`store` (row metadata), `field` (a record field) or `data` (the whole record).",
            "example": "field"
          },
          "field": {
            "description": "Record field read.",
            "example": "email",
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "Type in the unmasked views.",
            "example": "text"
          },
          "maskedType": {
            "type": "string",
            "description": "Type in the masked views.",
            "example": "text"
          },
          "class": {
            "type": "string",
            "description": "Classification: `public`, `internal`, `pii`, `financial` or `secret`.",
            "example": "pii"
          },
          "mask": {
            "description": "Mask in the masked views.",
            "example": "email",
            "type": "string"
          }
        },
        "required": [
          "name",
          "source",
          "type",
          "maskedType",
          "class"
        ],
        "additionalProperties": false,
        "description": "One column of a SQL view."
      },
      "SqlPrincipal": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Principal id.",
            "example": "3f9a1c2b-4d5e-4f60-8a7b-1c2d3e4f5a6b"
          },
          "username": {
            "type": "string",
            "description": "Postgres login name.",
            "example": "os_sql_metabase_prod_3f9a1c"
          },
          "label": {
            "type": "string",
            "description": "Label.",
            "example": "Metabase prod"
          },
          "pii": {
            "type": "boolean",
            "description": "Reads the unmasked schema.",
            "example": false
          },
          "scope": {
            "$ref": "#/components/schemas/SqlPrincipalScope"
          },
          "connectionLimit": {
            "type": "number",
            "description": "Concurrent sessions allowed.",
            "example": 5
          },
          "createdBy": {
            "description": "User id that created it.",
            "example": "b3c4d5e6-0000-4000-8000-000000000001",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "description": "Created (ISO 8601).",
            "example": "2026-09-29T12:00:00.000Z"
          },
          "expiresAt": {
            "description": "Login expiry (ISO 8601); null for never.",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "revokedAt": {
            "description": "When it was revoked (ISO 8601).",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "lastRotatedAt": {
            "description": "Last password rotation (ISO 8601).",
            "example": null,
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "description": "`active`, `expired` or `revoked`.",
            "example": "active"
          },
          "searchPath": {
            "type": "string",
            "description": "Schema the login reads by default.",
            "example": "os_analytics"
          }
        },
        "required": [
          "id",
          "username",
          "label",
          "pii",
          "scope",
          "connectionLimit",
          "createdBy",
          "createdAt",
          "expiresAt",
          "revokedAt",
          "lastRotatedAt",
          "status",
          "searchPath"
        ],
        "additionalProperties": false,
        "description": "A read-only SQL login. Never carries its password."
      },
      "SqlPrincipalScope": {
        "type": "object",
        "properties": {
          "tenants": {
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ],
            "description": "Owner tenants the login sees, or `*` for every tenant.",
            "example": [
              "acme"
            ]
          },
          "verticals": {
            "description": "Verticals the login sees; omitted or `*` for all.",
            "example": [
              "crm"
            ],
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          }
        },
        "required": [
          "tenants"
        ],
        "additionalProperties": false,
        "description": "What a SQL principal may read."
      },
      "SqlPrincipalWithPassword": {
        "type": "object",
        "properties": {
          "principal": {
            "$ref": "#/components/schemas/SqlPrincipal"
          },
          "password": {
            "type": "string",
            "description": "The password. Shown once, never stored — rotate if lost.",
            "example": "k3JqT9…"
          },
          "connection": {
            "$ref": "#/components/schemas/SqlPrincipalConnection"
          },
          "mode": {
            "type": "string",
            "enum": [
              "managed",
              "manual"
            ],
            "description": "Provisioning mode.",
            "example": "managed"
          },
          "sessionsTerminated": {
            "description": "Open sessions ended (rotate only); null when unknown.",
            "example": 0,
            "type": [
              "number",
              "null"
            ]
          },
          "script": {
            "description": "Manual mode: SQL an operator must run to apply the change. Holds only the SCRAM verifier, not the password.",
            "example": "BEGIN; … COMMIT;",
            "type": "string"
          }
        },
        "required": [
          "principal",
          "password",
          "connection",
          "mode"
        ],
        "additionalProperties": false,
        "description": "A principal with its one-time password."
      },
      "SqlPrincipalConnection": {
        "type": "object",
        "properties": {
          "host": {
            "description": "Advertised host (`ANALYTICS_READ_HOST`); null when unset — use the database host.",
            "example": "replica.internal",
            "type": [
              "string",
              "null"
            ]
          },
          "username": {
            "type": "string",
            "description": "Login name.",
            "example": "os_sql_metabase_prod_3f9a1c"
          },
          "searchPath": {
            "type": "string",
            "description": "Default schema.",
            "example": "os_analytics"
          }
        },
        "required": [
          "host",
          "username",
          "searchPath"
        ],
        "additionalProperties": false,
        "description": "How to connect as a principal."
      },
      "SqlPrincipalRevokeResult": {
        "type": "object",
        "properties": {
          "principal": {
            "$ref": "#/components/schemas/SqlPrincipal"
          },
          "mode": {
            "type": "string",
            "enum": [
              "managed",
              "manual"
            ],
            "description": "Provisioning mode.",
            "example": "managed"
          },
          "sessionsTerminated": {
            "description": "Open sessions ended; null when unknown.",
            "example": 0,
            "type": [
              "number",
              "null"
            ]
          },
          "script": {
            "description": "Manual mode: SQL an operator must run to apply the revoke.",
            "example": "BEGIN; … COMMIT;",
            "type": "string"
          }
        },
        "required": [
          "principal",
          "mode",
          "sessionsTerminated"
        ],
        "additionalProperties": false,
        "description": "Outcome of revoking a principal."
      },
      "ScopeGrantOutput": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Tenant the grant covers.",
            "example": "acme"
          },
          "verticals": {
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 64
                }
              }
            ],
            "description": "Verticals within the tenant: `*` for every vertical, or a list.",
            "example": "*"
          }
        },
        "required": [
          "tenantId",
          "verticals"
        ],
        "additionalProperties": false,
        "description": "Tenant (and optionally verticals) a scoped user may see."
      },
      "EndUserPiiOutput": {
        "type": "object",
        "properties": {
          "firstName": {
            "description": "End-user's given name.",
            "example": "Jane",
            "type": "string"
          },
          "lastName": {
            "description": "End-user's family name.",
            "example": "Doe",
            "type": "string"
          },
          "personalIdNumber": {
            "description": "National/tax identifier; typically masked in responses.",
            "example": "***-**-1234",
            "type": "string"
          },
          "phone": {
            "description": "Contact phone number in E.164 or local format.",
            "example": "+1-415-555-0142",
            "type": "string"
          },
          "address": {
            "description": "End-user's postal address.",
            "$ref": "#/components/schemas/EndUserAddressOutput"
          }
        },
        "additionalProperties": false,
        "description": "Personally identifiable information for an end-user; only returned when explicitly requested."
      },
      "EndUserAddressOutput": {
        "type": "object",
        "properties": {
          "line1": {
            "description": "First line of the street address.",
            "example": "2500 Market Street",
            "type": "string"
          },
          "line2": {
            "description": "Second address line (suite, unit, etc.).",
            "example": "Suite 300",
            "type": "string"
          },
          "city": {
            "description": "City or locality.",
            "example": "San Francisco",
            "type": "string"
          },
          "region": {
            "description": "State, province, or region.",
            "example": "CA",
            "type": "string"
          },
          "postalCode": {
            "description": "Postal or ZIP code.",
            "example": "94114",
            "type": "string"
          },
          "country": {
            "description": "Country, typically an ISO 3166-1 alpha-2 code.",
            "example": "US",
            "type": "string"
          }
        },
        "additionalProperties": false,
        "description": "Postal address for an end-user, stored as part of their PII."
      },
      "AllowedPlatformOutput": {
        "type": "object",
        "properties": {
          "vertical": {
            "type": "string",
            "minLength": 1,
            "description": "Vertical the allowed platform belongs to.",
            "example": "accounting"
          },
          "slug": {
            "type": "string",
            "minLength": 1,
            "description": "Slug of the platform the customer is allowed to connect.",
            "example": "xero"
          }
        },
        "required": [
          "vertical",
          "slug"
        ],
        "additionalProperties": false,
        "description": "A specific vertical+platform the customer is permitted to connect through a link."
      },
      "DashboardWidgetOutput": {
        "type": "object",
        "properties": {
          "metricId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "pattern": "^[a-z0-9][a-z0-9_.-]*$",
            "description": "Metric id from the catalog.",
            "example": "ecommerce.orders_per_day"
          },
          "title": {
            "description": "Heading shown on the widget; defaults to the metric title.",
            "example": "Orders (last 30 days)",
            "type": "string",
            "maxLength": 80
          },
          "chart": {
            "$ref": "#/components/schemas/DashboardChart"
          },
          "width": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12,
            "description": "Width in grid columns, out of 12.",
            "example": 6
          },
          "currency": {
            "description": "Pin the widget to one currency (ISO 4217). Absent or null follows the dashboard view's currency filter; with no filter every currency is drawn separately. Metrics without money or a currency field ignore it.",
            "example": "EUR",
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "granularity": {
            "$ref": "#/components/schemas/MetricGranularityParam"
          },
          "compare": {
            "description": "Also compute the prior equal-length period; number and gauge charts show the change. Only metrics marked `comparable` use it.",
            "example": true,
            "type": "boolean"
          }
        },
        "required": [
          "metricId",
          "chart",
          "width"
        ],
        "additionalProperties": false,
        "description": "One chart on a dashboard. `chart` must be one of its metric's `charts` (`400` otherwise)."
      },
      "DestinationScopeOutput": {
        "type": "object",
        "properties": {
          "tenants": {
            "anyOf": [
              {
                "type": "string",
                "const": "*"
              },
              {
                "maxItems": 1000,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                }
              }
            ],
            "description": "Owner tenants whose connections are exported, or `*` for every tenant (the only value that also exports connections with no owner tenant).",
            "example": [
              "acme"
            ]
          },
          "verticals": {
            "description": "Verticals exported, each with `*` or a list of resource types. Omit to export every vertical.",
            "example": {
              "crm": "*",
              "ecommerce": [
                "orders"
              ]
            },
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "string",
                  "const": "*"
                },
                {
                  "maxItems": 500,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  }
                }
              ]
            }
          },
          "maskFinancial": {
            "description": "Also mask financial fields (amounts, balances).",
            "example": false,
            "type": "boolean"
          }
        },
        "required": [
          "tenants"
        ],
        "additionalProperties": false,
        "description": "Which records a destination exports. Must lie inside your own tenant (and vertical) scope."
      }
    }
  },
  "paths": {
    "/version": {
      "get": {
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "operationId": "auth.login",
        "summary": "Sign in with username + password",
        "tags": [
          "auth"
        ],
        "description": "Exchange a username and password for a JWT used to authenticate subsequent admin-api calls. No prior authentication required. Subject to lockout after repeated failures (returns `429`, with a `Retry-After` header for temporary locks). Returns `400` if either field is missing, `401` on invalid credentials, and `403` when local login is disabled and the account is not the pinned break-glass admin (SSO-only). Writes a `user.login` audit entry on success.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginBody"
              }
            }
          },
          "description": "Credentials for local username/password login."
        },
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                },
                "examples": {
                  "admin": {
                    "summary": "Admin signs in",
                    "value": {
                      "token": "eyJhbGciOiJIUzI1NiJ9.olivia",
                      "user": {
                        "id": "usr_olivia",
                        "username": "olivia.admin",
                        "role": "admin"
                      }
                    }
                  },
                  "operator": {
                    "summary": "Operator signs in",
                    "value": {
                      "token": "eyJhbGciOiJIUzI1NiJ9.marco",
                      "user": {
                        "id": "usr_marco",
                        "username": "marco.ops",
                        "role": "operator"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "invalid-credentials": {
                    "summary": "Wrong username or password",
                    "value": {
                      "error": "Invalid credentials"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "sso-only": {
                    "summary": "Local password login disabled — SSO required",
                    "value": {
                      "error": "Local password login is disabled. Please sign in with your organization (SSO)."
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "locked-out": {
                    "summary": "Too many failed attempts — temporarily locked",
                    "value": {
                      "error": "Too many failed attempts — retry in 30s."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/has-users": {
      "get": {
        "operationId": "auth.hasUsers",
        "summary": "Whether any admin user exists yet (first-run check)",
        "tags": [
          "auth"
        ],
        "description": "Read-only check the setup wizard uses to decide whether to show the first-run form. No authentication required and no side effects. Returns `{ hasUsers: false }` on a fresh deployment, `{ hasUsers: true }` once the first admin has been created.",
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HasUsersResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/setup": {
      "post": {
        "operationId": "auth.setup",
        "summary": "First-run admin bootstrap (only succeeds when no users exist)",
        "tags": [
          "auth"
        ],
        "description": "Bootstrap the first `admin` account on a fresh deployment and return a JWT for it. Only succeeds while the user table is empty — returns `409` once any user exists. When the server is started with a `BOOTSTRAP_TOKEN`, the matching token must be supplied in the `X-Bootstrap-Token` header (else `401`), so a fresh or wiped deployment cannot be claimed by an attacker. When NO token is configured, setup is refused from non-loopback addresses (`403`) — a remote first-run must carry a `BOOTSTRAP_TOKEN`; only a caller on the deployment host may set up tokenless. The created admin is auto-pinned as the break-glass account so SSO can be locked down later without losing password access. Returns `400` if username or password is missing.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetupBody"
              }
            }
          },
          "description": "Credentials to bootstrap the first admin account on a fresh deployment."
        },
        "security": [],
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                },
                "examples": {
                  "created": {
                    "summary": "First-run admin created",
                    "value": {
                      "token": "eyJhbGciOiJIUzI1NiJ9.olivia",
                      "user": {
                        "id": "usr_olivia",
                        "username": "olivia.admin",
                        "role": "admin"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "already-completed": {
                    "summary": "Setup already ran — users exist",
                    "value": {
                      "error": "Setup already completed — users exist"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/me": {
      "get": {
        "operationId": "auth.me",
        "summary": "Return the calling user, with permissions and tenant scope",
        "tags": [
          "auth"
        ],
        "description": "Return the decoded JWT claims (id, username, role) for the currently authenticated operator, plus the caller's effective role (`roleId`, `roleName`), `permissions` and tenant `scope`. The last three are read from the database on each call (cached for a few seconds), so they reflect a role or scope change made since the token was issued. Any authenticated operator may call this; useful for confirming a token is valid and discovering what the caller may do. Returns `401` if the token is missing or invalid.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/users": {
      "get": {
        "operationId": "users.list",
        "summary": "List admin / operator / viewer accounts",
        "tags": [
          "users"
        ],
        "description": "List all admin-console user accounts with their roles and timestamps. Admin role required. Credentials are never returned.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "users.create",
        "summary": "Create a new user account",
        "tags": [
          "users"
        ],
        "description": "Create a new admin-console user with the given username, password, and role (`admin`, `operator`, or `viewer`), and optionally an email address. Admin role required. Returns `400` for a missing/invalid field (including a malformed email), an over-long username, or a password that fails policy, and `409` if the username is already taken. Writes a `user.create` audit entry, which records that an email was set but never the address.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUserBody"
              },
              "examples": {
                "admin": {
                  "summary": "Create an admin (full access)",
                  "value": {
                    "username": "olivia.admin",
                    "password": "s3cr3t-password",
                    "role": "admin"
                  }
                },
                "operator": {
                  "summary": "Create an operator (manage resources, no user admin)",
                  "value": {
                    "username": "marco.ops",
                    "password": "s3cr3t-password",
                    "role": "operator"
                  }
                },
                "viewer": {
                  "summary": "Create a viewer (read-only)",
                  "value": {
                    "username": "vera.view",
                    "password": "s3cr3t-password",
                    "role": "viewer"
                  }
                }
              }
            }
          },
          "description": "Request body to create an admin-console user."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreatedUser"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "admin": {
                    "summary": "Admin created",
                    "value": {
                      "data": {
                        "id": "usr_olivia",
                        "username": "olivia.admin",
                        "role": "admin"
                      }
                    }
                  },
                  "operator": {
                    "summary": "Operator created",
                    "value": {
                      "data": {
                        "id": "usr_marco",
                        "username": "marco.ops",
                        "role": "operator"
                      }
                    }
                  },
                  "viewer": {
                    "summary": "Viewer created",
                    "value": {
                      "data": {
                        "id": "usr_vera",
                        "username": "vera.view",
                        "role": "viewer"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Validation failed",
                    "value": {
                      "error": "Request validation failed.",
                      "code": "invalid_request"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Missing or invalid token",
                    "value": {
                      "error": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Insufficient role",
                    "value": {
                      "error": "Forbidden"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "duplicate": {
                    "summary": "Username already taken",
                    "value": {
                      "error": "Username already exists"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/users/{id}": {
      "get": {
        "operationId": "users.get",
        "summary": "Get one console account",
        "tags": [
          "users"
        ],
        "description": "Read one console account with its identity-provider links and break-glass status. Admin role required. Pass `include_identity=true` to reveal each link’s `externalId` — the subject this account maps to in the identity provider, which is typically a work email. That privileged path writes a `user.pii_reveal` audit entry; without the flag the field is absent, not masked.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/UserDetail"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "users.update",
        "summary": "Change a console account’s role, password and/or email",
        "tags": [
          "users"
        ],
        "description": "Update an existing account in place, preserving the user id and any break-glass pin. Admin role required. Refuses changing your own role (`400`), a demotion that would leave no password-usable local admin (`409`), a password that fails policy (`400`), a malformed email (`400`), and any change to another account that holds more than you (`403`). An email set here is owned by the console and SSO no longer overwrites it; `null` clears it. Writes a `user.update` audit entry (neither the password nor the email address is ever recorded — only `passwordChanged` / `emailChanged` flags).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUserBody"
              }
            }
          },
          "description": "Request body to update a console account."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/User"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "users.delete",
        "summary": "Delete a user account",
        "tags": [
          "users"
        ],
        "description": "Delete a user account and any linked SSO identities. Admin role required. Returns `400` if you attempt to delete your own account, `409` if removing this user would leave no break-glass admin, and `404` if no user matches the id. Writes a `user.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/users/{id}/avatar": {
      "put": {
        "operationId": "users.avatar.put",
        "summary": "Upload a console user's profile picture",
        "tags": [
          "users"
        ],
        "description": "Store a profile picture (PNG, JPEG or WebP, at most 512 KB) for a console account, replacing any existing one — including one fetched from the identity provider, which SSO then no longer replaces. Any signed-in user may set their own; setting another user’s needs `users:manage`, and is refused (`403`) when that account holds more than you or sees tenants outside your scope. The type is identified from the bytes: `415` for anything else (SVG included, whatever the data URL declares), `413` when too large, `400` when `data` is not base64. `404` for an unknown user. Writes a `user.avatar_update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PutUserAvatarBody"
              }
            }
          },
          "description": "A profile picture to store for a console user."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/UserAvatar"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "413": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "415": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "users.avatar.delete",
        "summary": "Remove a console user's profile picture",
        "tags": [
          "users"
        ],
        "description": "Remove a console account’s profile picture, whichever source it came from; the console then shows initials. Idempotent (`204` when there was none). Any signed-in user may remove their own; removing another user’s needs `users:manage`, with the same `403` escalation guards as uploading. A picture sourced from the identity provider comes back at the next SSO sign-in if the IdP still sends one. `404` for an unknown user. Writes a `user.avatar_delete` audit entry when a picture was removed.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/permissions": {
      "get": {
        "operationId": "permissions.list",
        "summary": "List the permission catalog",
        "tags": [
          "roles"
        ],
        "description": "List every permission a role can grant, what it allows, and which built-in roles hold it. Any authenticated user.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PermissionInfo"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/roles": {
      "get": {
        "operationId": "roles.list",
        "summary": "List roles",
        "tags": [
          "roles"
        ],
        "description": "List the three built-in roles followed by every custom role, each with its effective permissions. Requires `roles:manage` or `users:manage`.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RoleDefinition"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "roles.create",
        "summary": "Create a custom role",
        "tags": [
          "roles"
        ],
        "description": "Create a custom role from a base role and a permission set. Requires `roles:manage`. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. Returns `403` when the role would grant a permission or base role you do not hold yourself, and `409` when the name is taken (case-insensitively). Writes a `role.create` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRoleBody"
              }
            }
          },
          "description": "Request body to create a custom role."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoleDefinition"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/roles/{id}": {
      "get": {
        "operationId": "roles.get",
        "summary": "Read one role",
        "tags": [
          "roles"
        ],
        "description": "Read a built-in or custom role by id. Requires `roles:manage` or `users:manage`. Returns `404` if no role matches.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoleDefinition"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "roles.update",
        "summary": "Edit a custom role",
        "tags": [
          "roles"
        ],
        "description": "Edit a custom role; omitted fields are unchanged. A base-role change is applied to every holder at once. A role cannot become admin-based while any holder is limited to specific tenants (`409`): admins always have every tenant. Requires `roles:manage`. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. Returns `404` if the role does not exist, `409` for a built-in role (they are immutable) or a taken name, and `403` when either the role as it stands or the edit would grant a permission or base role you do not hold. Holders see the change within seconds; role-gated routes read the current base role from the database, not the sign-in token. Writes a `role.update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateRoleBody"
              }
            }
          },
          "description": "Request body to edit a custom role; omitted fields are unchanged."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoleDefinition"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "roles.delete",
        "summary": "Delete a custom role",
        "tags": [
          "roles"
        ],
        "description": "Delete a custom role. Requires `roles:manage`. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. Returns `404` if it does not exist, `403` if it grants more than you hold, and `409` for a built-in role or one still in use — assigned to a user or named by an identity-provider role-mapping rule. Reassign those first. Writes a `role.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/users/{id}/role": {
      "put": {
        "operationId": "users.role.assign",
        "summary": "Assign a console user's role",
        "tags": [
          "roles"
        ],
        "description": "Assign a built-in or custom role to a console user. `users.role` is set to the role’s base role in the same write. Requires `users:manage`. Returns `404` for an unknown user, `400` for an unknown role or an attempt to change your own role, `403` when either the new role or the user’s current role grants more than you hold, or the user sees tenants you cannot, and `409` when it would demote the last password-usable local admin. Permissions change within seconds; role-gated routes read the current base role from the database, not the sign-in token. Making a user an admin gives them every tenant: a tenant restriction is cleared (audited as `scopeCleared`). Writes a `user.role_assign` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssignUserRoleBody"
              }
            }
          },
          "description": "Request body to assign a role to a console user."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/User"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/users/{id}/scope": {
      "put": {
        "operationId": "users.scope.update",
        "summary": "Set a console user's tenant scope",
        "tags": [
          "roles"
        ],
        "description": "Restrict a console user to specific tenants (optionally specific verticals within them), or give them every tenant with `mode: \"all\"`. Requires `users:manage`. A restricted user sees only granted tenants’ connections, sync jobs and tenants, gets `404` for anything else, and is refused (`403 SCOPE_RESTRICTED`) on surfaces that are not tenant-scoped yet. An admin cannot be restricted (`400`): admins always have every tenant. Returns `404` for an unknown user, `400` for an unknown tenant, and `403` when either the requested scope or the user’s current one reaches beyond yours. Takes effect within seconds. Writes a `user.scope_update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetUserScopeBody"
              }
            }
          },
          "description": "Request body to set a console user's tenant scope."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/UserScope"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/verticals": {
      "get": {
        "operationId": "verticals.list",
        "summary": "List enabled verticals + per-vertical health",
        "tags": [
          "verticals"
        ],
        "description": "List the configured verticals along with a live health check for each (e.g. whether its backing service is reachable). Any authenticated operator. Useful for a system-status dashboard.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/VerticalHealth"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/connections": {
      "get": {
        "operationId": "connections.list",
        "summary": "List connections across every configured vertical",
        "tags": [
          "connections"
        ],
        "description": "List all active integration connections aggregated across every configured vertical, with optional filters for `vertical`, `status`, `platform`, per-column filters (`f_label`, `f_id`, `f_vertical`, `f_status`, `f_platform`, `f_tenant`), a `search` over connection id and label, and `sort`/`dir` to order the result. Filters apply before pagination, so `meta.total` reflects the filtered set, and sorting is applied before the slice, so every page reflects the requested order. A tenant-restricted caller sees only connections owned by its granted tenants (and verticals); connections with no tenant are hidden from it. Any authenticated operator.",
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/Vertical"
            },
            "in": "query",
            "name": "vertical"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "status"
          },
          {
            "schema": {
              "type": "string",
              "description": "Adapter slug identifying an upstream platform, e.g. `fortnox`. See GET /api/platforms.",
              "example": "fortnox"
            },
            "in": "query",
            "name": "platform"
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the connection id and label. An id prefix is enough, which is what an operator pastes from a support ticket or a `?connection_id=` call.",
              "example": "9f8e7d6c",
              "type": "string"
            },
            "in": "query",
            "name": "search",
            "description": "Case-insensitive substring match against the connection id and label. An id prefix is enough, which is what an operator pastes from a support ticket or a `?connection_id=` call."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "page"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "limit"
          },
          {
            "schema": {
              "description": "Column to order by: one of `label`, `id`, `vertical`, `platform`, `status`, `tenant`, `created`. An unrecognised value is ignored and the default order (most recently updated first) is used.",
              "example": "label",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "sort",
            "description": "Column to order by: one of `label`, `id`, `vertical`, `platform`, `status`, `tenant`, `created`. An unrecognised value is ignored and the default order (most recently updated first) is used."
          },
          {
            "schema": {
              "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending.",
              "example": "desc",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "dir",
            "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the label.",
              "example": "acme",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "f_label",
            "description": "Case-insensitive substring match against the label."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the connection id.",
              "example": "9f8e7d6c",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "f_id",
            "description": "Case-insensitive substring match against the connection id."
          },
          {
            "schema": {
              "description": "Exact match against the vertical.",
              "example": "accounting",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "f_vertical",
            "description": "Exact match against the vertical."
          },
          {
            "schema": {
              "description": "Exact match against the connection status.",
              "example": "valid",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "f_status",
            "description": "Exact match against the connection status."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the platform slug.",
              "example": "fortnox",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "f_platform",
            "description": "Case-insensitive substring match against the platform slug."
          },
          {
            "schema": {
              "description": "Exact match against the tenant id.",
              "example": "acme",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "f_tenant",
            "description": "Exact match against the tenant id."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Connection"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/connections/{vertical}/{id}": {
      "get": {
        "operationId": "connections.get",
        "summary": "Fetch a single connection",
        "tags": [
          "connections"
        ],
        "description": "Fetch one connection by its vertical and id. Any authenticated operator. Returns `404` if the vertical is unknown, no connection with that id exists in it, or the connection belongs to a tenant outside the caller's scope.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "accounting",
                "crm",
                "ecommerce",
                "logistics",
                "payments",
                "docsign",
                "projects",
                "customer-support",
                "inventory"
              ],
              "description": "One of the nine verticals OpenSteward maps to a canonical API.",
              "example": "accounting"
            },
            "in": "path",
            "name": "vertical",
            "required": true,
            "description": "One of the nine verticals OpenSteward maps to a canonical API."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Connection"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "connections.update",
        "summary": "Rename a connection",
        "tags": [
          "connections"
        ],
        "description": "Rename a connection by vertical and id. The label is the only mutable field — it is what the admin UI and `GET /api/connections?search=` match on, so it is how an operator tells two connections to the same platform apart. Send `null` to clear it. Operator role or higher. Returns `404` if the vertical is unknown or the connection is not found, and `409` if another connection for the same tenant and platform already carries that label. Writes a `connection.update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "description": "New human-friendly name for the connection. `null` clears it. Labels are unique per tenant and platform, so reusing one answers `409`.",
                    "example": "Acme production books",
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "label"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "accounting",
                "crm",
                "ecommerce",
                "logistics",
                "payments",
                "docsign",
                "projects",
                "customer-support",
                "inventory"
              ],
              "description": "One of the nine verticals OpenSteward maps to a canonical API.",
              "example": "accounting"
            },
            "in": "path",
            "name": "vertical",
            "required": true,
            "description": "One of the nine verticals OpenSteward maps to a canonical API."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Connection"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "connections.delete",
        "summary": "Revoke a connection",
        "tags": [
          "connections"
        ],
        "description": "Revoke a connection by vertical and id, deleting its stored credentials. Operator role or higher. Returns `404` if the vertical is unknown or the connection is not found. Writes a `connection.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "accounting",
                "crm",
                "ecommerce",
                "logistics",
                "payments",
                "docsign",
                "projects",
                "customer-support",
                "inventory"
              ],
              "description": "One of the nine verticals OpenSteward maps to a canonical API.",
              "example": "accounting"
            },
            "in": "path",
            "name": "vertical",
            "required": true,
            "description": "One of the nine verticals OpenSteward maps to a canonical API."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/connections/{vertical}/{id}/sync-schedule": {
      "put": {
        "operationId": "connections.setSyncSchedule",
        "summary": "Set a connection's sync schedule",
        "tags": [
          "connections"
        ],
        "description": "Choose how often a connection's data is re-synced: `default` (the deployment interval), `custom` (every `intervalMinutes`, 15–43200), `trigger_only` (only when a sync is requested — never automatically) or `once` (one sync when connected). Takes effect on the scheduler's next tick. Operator role or higher. Returns `404` if the vertical is unknown, the connection is not found, or it belongs to a tenant outside the caller's scope; `400` for an invalid schedule. Writes a `connection.sync_schedule` audit entry with the previous and new schedule.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConnectionSyncSchedule"
              }
            }
          },
          "description": "How often a connection's data is re-synced. `default` follows the deployment interval (runtime setting `data_store.sync.default_interval_minutes`); `custom` uses `intervalMinutes` (15–43200); `trigger_only` never syncs automatically, not even when connected; `once` syncs once when connected."
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "accounting",
                "crm",
                "ecommerce",
                "logistics",
                "payments",
                "docsign",
                "projects",
                "customer-support",
                "inventory"
              ],
              "description": "One of the nine verticals OpenSteward maps to a canonical API.",
              "example": "accounting"
            },
            "in": "path",
            "name": "vertical",
            "required": true,
            "description": "One of the nine verticals OpenSteward maps to a canonical API."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Connection"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/notifications": {
      "get": {
        "operationId": "notifications.list",
        "summary": "List unacknowledged notifications",
        "tags": [
          "notifications"
        ],
        "description": "List notifications that have not yet been acknowledged (e.g. connection errors or sync alerts surfaced to operators). Any authenticated operator. A tenant-restricted user gets none (notifications are not tenant-scoped yet).",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Notification"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/notifications/unread-count": {
      "get": {
        "operationId": "notifications.unread-count",
        "summary": "Count unread notifications",
        "tags": [
          "notifications"
        ],
        "description": "The number of unacknowledged notifications, excluding `credential_expiring` (it auto-heals within a poll, so counting it would keep the header bell from ever reading zero). Any authenticated operator. A tenant-restricted user gets none (notifications are not tenant-scoped yet).",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/UnreadNotificationCount"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/notifications/{id}/acknowledge": {
      "post": {
        "operationId": "notifications.acknowledge",
        "summary": "Acknowledge a single notification",
        "tags": [
          "notifications"
        ],
        "description": "Mark a single notification as acknowledged so it drops out of the unacknowledged list. Operator role or higher. Returns `404` if no notification matches the id. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/notifications/acknowledge-all": {
      "post": {
        "operationId": "notifications.acknowledge-all",
        "summary": "Acknowledge every notification",
        "tags": [
          "notifications"
        ],
        "description": "Acknowledge every outstanding notification in one call, clearing the unacknowledged list. Operator role or higher. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant.",
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/audit/actions": {
      "get": {
        "operationId": "audit.actions",
        "summary": "Every audit action the registry knows",
        "tags": [
          "audit"
        ],
        "description": "The typed action vocabulary, for building filter UIs without hand-typing exact dotted action literals. Admin role required.",
        "responses": {
          "200": {
            "description": "Default Response"
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/audit": {
      "get": {
        "operationId": "audit.list",
        "summary": "List audit-log entries, newest first",
        "tags": [
          "audit"
        ],
        "description": "List operator audit-log entries (paginated, newest first; `limit` capped at 200). Admin role required. Supports filtering by `action`, `user_id`, `target_id` (exact match on the acted-on id — “everything that happened to key X”), `vertical` (case-insensitive substring), and a `from`/`to` date range (ISO-8601 or epoch-ms), plus `sort`/`dir` to order the result. Filters and ordering are applied in SQL before the page slice, so `meta.total` reflects the filtered set and every page reflects the requested order.",
        "parameters": [
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "page"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "limit"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "action"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "user_id"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "target_id"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "from"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "to"
          },
          {
            "schema": {
              "description": "Column to order by: one of `time`, `user`, `action`, `vertical`, `target`. An unrecognised value is ignored and the default order (newest first) is used. `user` orders by the stored `user_id`, not the username resolved for display.",
              "example": "action",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "sort",
            "description": "Column to order by: one of `time`, `user`, `action`, `vertical`, `target`. An unrecognised value is ignored and the default order (newest first) is used. `user` orders by the stored `user_id`, not the username resolved for display."
          },
          {
            "schema": {
              "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending.",
              "example": "desc",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "dir",
            "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the vertical the action touched.",
              "example": "accounting",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "vertical",
            "description": "Case-insensitive substring match against the vertical the action touched."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AuditEntry"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "mixed": {
                    "summary": "Recent entries mixing mint, login, and connection actions",
                    "value": {
                      "data": [
                        {
                          "id": 1042,
                          "user_id": "usr_olivia",
                          "action": "api_key.mint",
                          "vertical": null,
                          "target_id": "key_1042",
                          "detail": {
                            "action": "api_key.mint"
                          },
                          "created_at": 1769949600000
                        },
                        {
                          "id": 1041,
                          "user_id": "usr_olivia",
                          "action": "user.login",
                          "vertical": null,
                          "target_id": null,
                          "detail": {
                            "action": "user.login"
                          },
                          "created_at": 1768469400000
                        },
                        {
                          "id": 1040,
                          "user_id": "usr_marco",
                          "action": "connection.create",
                          "vertical": "accounting",
                          "target_id": "conn_1042",
                          "detail": {
                            "action": "connection.create"
                          },
                          "created_at": 1768469400000
                        }
                      ],
                      "meta": {
                        "page": 1,
                        "limit": 50,
                        "total": 1042
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Missing or invalid token",
                    "value": {
                      "error": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Insufficient role",
                    "value": {
                      "error": "Forbidden"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/audit/export": {
      "get": {
        "operationId": "audit.export",
        "summary": "Export audit-log entries as CSV or JSON",
        "tags": [
          "audit"
        ],
        "description": "Export the (optionally filtered) audit log as a downloadable `csv` (default) or `json` attachment, supporting the same filters as the list endpoint. Admin role required. Streamed from a SQLite cursor so large logs do not materialise at once, and the export itself is recorded as an `audit.export` audit entry.",
        "parameters": [
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "page"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "limit"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "action"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "user_id"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "target_id"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "from"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "to"
          },
          {
            "schema": {
              "description": "Column to order by: one of `time`, `user`, `action`, `vertical`, `target`. An unrecognised value is ignored and the default order (newest first) is used. `user` orders by the stored `user_id`, not the username resolved for display.",
              "example": "action",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "sort",
            "description": "Column to order by: one of `time`, `user`, `action`, `vertical`, `target`. An unrecognised value is ignored and the default order (newest first) is used. `user` orders by the stored `user_id`, not the username resolved for display."
          },
          {
            "schema": {
              "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending.",
              "example": "desc",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "dir",
            "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the vertical the action touched.",
              "example": "accounting",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "vertical",
            "description": "Case-insensitive substring match against the vertical the action touched."
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "csv",
                    "json"
                  ]
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "csv",
                      "json"
                    ]
                  }
                }
              ]
            },
            "in": "query",
            "name": "format"
          }
        ],
        "responses": {
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/platforms": {
      "get": {
        "operationId": "platforms.list",
        "summary": "List platforms across every vertical",
        "tags": [
          "platforms"
        ],
        "description": "List every available platform (integration adapter) across all verticals, with optional `vertical` and free-text `search` filters. Any authenticated operator. Includes each platform's `authType` and enabled state.",
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/Vertical"
            },
            "in": "query",
            "name": "vertical"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "search"
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Platform"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/platforms/status": {
      "get": {
        "operationId": "platforms.list-status",
        "summary": "List operator enable/config state for every platform",
        "tags": [
          "platforms"
        ],
        "description": "List every platform across every vertical with its operator-facing enabled/config state. The all-verticals counterpart of `/api/verticals/{vertical}/platforms`; each row carries the `vertical` it belongs to. Any authenticated operator. Returns `502` if integration-server cannot be reached.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PlatformOperatorRow"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/verticals/{vertical}/platforms": {
      "get": {
        "operationId": "platforms.list-by-vertical",
        "summary": "List platforms in one vertical",
        "tags": [
          "platforms"
        ],
        "description": "List the platforms available within a single vertical, with operator-facing enabled/config state. Any authenticated operator. Returns `404` if the vertical is unknown and `502` if integration-server cannot be reached.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "accounting",
                "crm",
                "ecommerce",
                "logistics",
                "payments",
                "docsign",
                "projects",
                "customer-support",
                "inventory"
              ],
              "description": "One of the nine verticals OpenSteward maps to a canonical API.",
              "example": "accounting"
            },
            "in": "path",
            "name": "vertical",
            "required": true,
            "description": "One of the nine verticals OpenSteward maps to a canonical API."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PlatformOperatorRow"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/verticals/{vertical}/platforms/{slug}/config": {
      "get": {
        "operationId": "platforms.config.get",
        "summary": "Read a platform's operator-set config (redacted)",
        "tags": [
          "platforms"
        ],
        "description": "Read the operator-managed configuration for a platform, with secret fields redacted. Operator role or higher. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. Returns `404` if the vertical or platform is unknown and `502` if integration-server cannot be reached.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "accounting",
                "crm",
                "ecommerce",
                "logistics",
                "payments",
                "docsign",
                "projects",
                "customer-support",
                "inventory"
              ],
              "description": "One of the nine verticals OpenSteward maps to a canonical API.",
              "example": "accounting"
            },
            "in": "path",
            "name": "vertical",
            "required": true,
            "description": "One of the nine verticals OpenSteward maps to a canonical API."
          },
          {
            "schema": {
              "type": "string",
              "description": "Adapter slug identifying an upstream platform, e.g. `fortnox`. See GET /api/platforms.",
              "example": "fortnox"
            },
            "in": "path",
            "name": "slug",
            "required": true,
            "description": "Adapter slug identifying an upstream platform, e.g. `fortnox`. See GET /api/platforms."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PlatformConfigRedacted"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "platforms.config.set",
        "summary": "Set a platform's operator-managed config",
        "tags": [
          "platforms"
        ],
        "description": "Set or replace the operator-managed configuration (credentials, keyed by `authType`) for a platform. Operator role or higher. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. Returns `404` if the vertical is unknown, `400` if the body lacks a `config` object, and `502` if integration-server cannot be reached. Writes an `adapter.config` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlatformConfigSetBody"
              }
            }
          },
          "description": "Request body to merge keys into an operator platform configuration. Omitted keys keep their stored value; `null` clears a key."
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "accounting",
                "crm",
                "ecommerce",
                "logistics",
                "payments",
                "docsign",
                "projects",
                "customer-support",
                "inventory"
              ],
              "description": "One of the nine verticals OpenSteward maps to a canonical API.",
              "example": "accounting"
            },
            "in": "path",
            "name": "vertical",
            "required": true,
            "description": "One of the nine verticals OpenSteward maps to a canonical API."
          },
          {
            "schema": {
              "type": "string",
              "description": "Adapter slug identifying an upstream platform, e.g. `fortnox`. See GET /api/platforms.",
              "example": "fortnox"
            },
            "in": "path",
            "name": "slug",
            "required": true,
            "description": "Adapter slug identifying an upstream platform, e.g. `fortnox`. See GET /api/platforms."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  },
                  "required": [
                    "ok"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/verticals/{vertical}/platforms/{slug}/enable": {
      "post": {
        "operationId": "platforms.enable",
        "summary": "Enable a platform with operator-supplied config",
        "tags": [
          "platforms"
        ],
        "description": "Enable a platform for a vertical, optionally applying operator credentials/config; omit `config` for adapters that need none. Operator role or higher. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. Returns `404` if the vertical is unknown and `502` if integration-server cannot be reached. Writes an `adapter.enable` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlatformEnableBody"
              }
            }
          },
          "description": "Request body to enable a platform for a vertical, optionally supplying its config."
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "accounting",
                "crm",
                "ecommerce",
                "logistics",
                "payments",
                "docsign",
                "projects",
                "customer-support",
                "inventory"
              ],
              "description": "One of the nine verticals OpenSteward maps to a canonical API.",
              "example": "accounting"
            },
            "in": "path",
            "name": "vertical",
            "required": true,
            "description": "One of the nine verticals OpenSteward maps to a canonical API."
          },
          {
            "schema": {
              "type": "string",
              "description": "Adapter slug identifying an upstream platform, e.g. `fortnox`. See GET /api/platforms.",
              "example": "fortnox"
            },
            "in": "path",
            "name": "slug",
            "required": true,
            "description": "Adapter slug identifying an upstream platform, e.g. `fortnox`. See GET /api/platforms."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  },
                  "required": [
                    "ok"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/verticals/{vertical}/platforms/{slug}/disable": {
      "post": {
        "operationId": "platforms.disable",
        "summary": "Disable a platform",
        "tags": [
          "platforms"
        ],
        "description": "Disable a platform for a vertical so it can no longer be connected. Operator role or higher. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. Returns `404` if the vertical is unknown and `502` if integration-server cannot be reached. Writes an `adapter.disable` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "accounting",
                "crm",
                "ecommerce",
                "logistics",
                "payments",
                "docsign",
                "projects",
                "customer-support",
                "inventory"
              ],
              "description": "One of the nine verticals OpenSteward maps to a canonical API.",
              "example": "accounting"
            },
            "in": "path",
            "name": "vertical",
            "required": true,
            "description": "One of the nine verticals OpenSteward maps to a canonical API."
          },
          {
            "schema": {
              "type": "string",
              "description": "Adapter slug identifying an upstream platform, e.g. `fortnox`. See GET /api/platforms.",
              "example": "fortnox"
            },
            "in": "path",
            "name": "slug",
            "required": true,
            "description": "Adapter slug identifying an upstream platform, e.g. `fortnox`. See GET /api/platforms."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  },
                  "required": [
                    "ok"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/company-info": {
      "get": {
        "operationId": "company-info.get",
        "summary": "Read the company-info record (auth-required)",
        "tags": [
          "company-info"
        ],
        "description": "Read the full company-info record (branding plus operator settings) so the admin UI can render the navbar logo and settings forms. Any authenticated operator. Returns `data: null` when no record has been saved yet.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "anyOf": [
                        {
                          "$ref": "#/components/schemas/CompanyInfoRecord"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "company-info.update",
        "summary": "Upsert the company-info record",
        "tags": [
          "company-info"
        ],
        "description": "Create or replace the single company-info record (branding and operator settings). Admin role required. Returns `400` with validation issues if the body fails schema validation. Writes a `company_info.update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompanyInfoInput"
              }
            }
          },
          "description": "Editable company/branding fields accepted when updating company info."
        },
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CompanyInfoRecord"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "company-info.reset",
        "summary": "Reset the company-info record to the defaults",
        "tags": [
          "company-info"
        ],
        "description": "Delete the company-info record (branding and operator settings), returning the deployment to the defaults it ships with: `GET /api/company-info` answers `data: null` again and every branded surface falls back to OpenSteward's own. Admin role required. Idempotent — resetting when nothing is saved also answers `204`. Writes a `company_info.reset` audit entry.",
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/company-info/public": {
      "get": {
        "operationId": "company-info.get-public",
        "summary": "Public branding subset (no auth)",
        "tags": [
          "company-info"
        ],
        "description": "Return only the public branding subset (name, logo, colours, support email, privacy/ToS links, base URL) with **no authentication**. Consumed server-to-server by the hosted Connect Link page to render the host's brand. Sensitive operator settings are never exposed here.",
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PublicCompanyInfo"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/end-users": {
      "get": {
        "operationId": "end-users.list",
        "summary": "List end-users (Connect Link customers)",
        "tags": [
          "end-users"
        ],
        "description": "List end-users (the customers who authorize integrations through Connect Link), with optional `tenantId`, free-text `q`, and `limit`/`offset` pagination. Any authenticated operator. PII is omitted from the summary view.",
        "parameters": [
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "tenantId"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "q"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "limit"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "offset"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "page"
          },
          {
            "schema": {
              "description": "Column to order by: one of `email`, `displayName`, `externalReference`, `tenantId`, `created`. An unrecognised value is ignored and the default order (most recently created first) is used.",
              "example": "email",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "sort",
            "description": "Column to order by: one of `email`, `displayName`, `externalReference`, `tenantId`, `created`. An unrecognised value is ignored and the default order (most recently created first) is used."
          },
          {
            "schema": {
              "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending.",
              "example": "desc",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "dir",
            "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the email address.",
              "example": "jane",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "email",
            "description": "Case-insensitive substring match against the email address."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the display name.",
              "example": "Jane",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "displayName",
            "description": "Case-insensitive substring match against the display name."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the external reference.",
              "example": "crm-100",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "externalReference",
            "description": "Case-insensitive substring match against the external reference."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EndUserSummary"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "end-users.create",
        "summary": "Create a new end-user",
        "tags": [
          "end-users"
        ],
        "description": "Create a new end-user record. Operator role or higher. Writes an `end_user.create` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateEndUserBody"
              }
            }
          },
          "description": "Request body to create an end-user."
        },
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EndUserSummary"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/end-users/{id}": {
      "get": {
        "operationId": "end-users.get",
        "summary": "Read a single end-user",
        "tags": [
          "end-users"
        ],
        "description": "Read one end-user by id. Any authenticated operator. Pass `include_pii=true` to reveal sensitive personal-ID fields — that privileged path requires the **admin** role (returns `403` otherwise) and writes an `end_user.pii_reveal` audit entry. Returns `404` if the end-user does not exist.",
        "parameters": [
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "include_pii"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EndUserDetail"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "end-users.update",
        "summary": "Patch an end-user",
        "tags": [
          "end-users"
        ],
        "description": "Partially update an end-user; only the supplied fields are changed. Operator role or higher. Writes an `end_user.update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateEndUserBody"
              }
            }
          },
          "description": "Request body to update an end-user; omitted fields are left unchanged."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EndUserSummary"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "end-users.delete",
        "summary": "Delete an end-user",
        "tags": [
          "end-users"
        ],
        "description": "Delete an end-user record. Admin role required. Writes an `end_user.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/connect-sessions": {
      "get": {
        "operationId": "connect-sessions.list",
        "summary": "List Connect Link sessions",
        "tags": [
          "connect-sessions"
        ],
        "description": "List Connect Link sessions (the hosted authorization flows end-users complete to link an integration), with optional filters for `tenantId`, `endUserId`, `status`, and `limit`/`offset` pagination. Any authenticated operator.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "tenantId"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "endUserId"
          },
          {
            "schema": {
              "$ref": "#/components/schemas/ConnectSessionStatus"
            },
            "in": "query",
            "name": "status"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "limit"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ConnectSession"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "mixed": {
                    "summary": "Sessions across the lifecycle: active, consumed, expired",
                    "value": {
                      "data": [
                        {
                          "id": "cs_8f3a2b9c4d",
                          "token": "cl_8f3a2b9c4d",
                          "tenantId": "acme",
                          "endUserId": "cus_4Qm2Xa9Lr",
                          "label": "Acme onboarding",
                          "allowedVerticals": [
                            "accounting"
                          ],
                          "allowedPlatforms": [
                            {
                              "vertical": "accounting",
                              "slug": "xero"
                            }
                          ],
                          "redirectUrl": "https://app.acme.example/return",
                          "expiresAt": 1769949600000,
                          "consumedAt": null,
                          "connectionId": null,
                          "createdAt": 1768469400000,
                          "createdBy": "usr_olivia",
                          "status": "active",
                          "oneTimeOnly": false,
                          "url": "https://connect.northwind.example/cl_8f3a2b9c4d"
                        },
                        {
                          "id": "cs_1b2c3d4e5f",
                          "token": "cl_1b2c3d4e5f",
                          "tenantId": "acme",
                          "endUserId": "cus_4Qm2Xa9Lr",
                          "label": "Acme onboarding",
                          "allowedVerticals": [
                            "accounting"
                          ],
                          "allowedPlatforms": [
                            {
                              "vertical": "accounting",
                              "slug": "xero"
                            }
                          ],
                          "redirectUrl": "https://app.acme.example/return",
                          "expiresAt": 1769949600000,
                          "consumedAt": 1769949600000,
                          "connectionId": "conn_1042",
                          "createdAt": 1768469400000,
                          "createdBy": "usr_olivia",
                          "status": "consumed",
                          "oneTimeOnly": false,
                          "url": "https://connect.northwind.example/cl_1b2c3d4e5f"
                        },
                        {
                          "id": "cs_9z8y7x6w5v",
                          "token": "cl_9z8y7x6w5v",
                          "tenantId": "acme",
                          "endUserId": null,
                          "label": "Acme onboarding",
                          "allowedVerticals": [
                            "accounting"
                          ],
                          "allowedPlatforms": [
                            {
                              "vertical": "accounting",
                              "slug": "xero"
                            }
                          ],
                          "redirectUrl": "https://app.acme.example/return",
                          "expiresAt": 1768469400000,
                          "consumedAt": null,
                          "connectionId": null,
                          "createdAt": 1768469400000,
                          "createdBy": "usr_olivia",
                          "status": "expired",
                          "oneTimeOnly": false,
                          "url": "https://connect.northwind.example/cl_9z8y7x6w5v"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Missing or invalid token",
                    "value": {
                      "error": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Insufficient role",
                    "value": {
                      "error": "Forbidden"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "connect-sessions.create",
        "summary": "Mint a Connect Link session",
        "tags": [
          "connect-sessions"
        ],
        "description": "Mint a new Connect Link session and return its hosted authorization URL to hand to an end-user. Operator role or higher. The requesting operator is recorded as `created_by`. Writes a `connect_session.create` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConnectSessionBody"
              }
            }
          },
          "description": "Request body to create a connect session / shareable connect link."
        },
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ConnectSession"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/connect-sessions/{id}": {
      "get": {
        "operationId": "connect-sessions.get",
        "summary": "Read one Connect Link session",
        "tags": [
          "connect-sessions"
        ],
        "description": "Read a single Connect Link session by id, including its current status. Any authenticated operator. Returns `404` if the session does not exist.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ConnectSession"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "connect-sessions.delete",
        "summary": "Revoke a Connect Link session",
        "tags": [
          "connect-sessions"
        ],
        "description": "Revoke a Connect Link session by id, invalidating its authorization URL immediately. Operator role or higher. Writes a `connect_session.revoke` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/api-keys": {
      "get": {
        "operationId": "api-keys.list",
        "summary": "List tenant API keys (active + revoked)",
        "tags": [
          "api-keys"
        ],
        "description": "List developer API keys (both active and revoked) for the deployment, optionally filtered to one tenant via `tenantId` and to one key mode via `mode`. Operator role or higher — an operator can check whether a key is active without being able to mint one. Returns key metadata only; the plaintext secret is never included.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "tenantId"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "live",
                "test"
              ]
            },
            "in": "query",
            "name": "mode"
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKey"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "masked-list": {
                    "summary": "Active + revoked keys, prefix only (no plaintext)",
                    "value": {
                      "data": [
                        {
                          "id": "key_1042",
                          "tenantId": "acme",
                          "prefix": "osk_acme_8f3a",
                          "label": "Production key",
                          "scopes": [
                            "customers:read",
                            "connections:read"
                          ],
                          "createdAt": 1768469400000,
                          "lastUsedAt": 1769949600000,
                          "revokedAt": null
                        },
                        {
                          "id": "key_0987",
                          "tenantId": "acme",
                          "prefix": "osk_acme_2c4e",
                          "label": "Rotated key",
                          "scopes": [
                            "customers:read",
                            "connections:read"
                          ],
                          "createdAt": 1768469400000,
                          "lastUsedAt": null,
                          "revokedAt": 1769949600000
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Missing or invalid token",
                    "value": {
                      "error": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Insufficient role",
                    "value": {
                      "error": "Forbidden"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "api-keys.create",
        "summary": "Mint a new tenant API key (plaintext returned once)",
        "tags": [
          "api-keys"
        ],
        "description": "Mint a new tenant-scoped developer API key. Admin role required. The response includes the plaintext key **once** — it is not stored and cannot be retrieved again. Returns `400` if `tenantId` is missing. Writes an `api_key.mint` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MintApiKeyBody"
              },
              "examples": {
                "minted": {
                  "summary": "Mint a scoped tenant key",
                  "value": {
                    "tenantId": "acme",
                    "label": "Production key",
                    "scopes": [
                      "customers:read",
                      "connections:read"
                    ]
                  }
                }
              }
            }
          },
          "description": "Request body to mint a new tenant API key."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ApiKeyMint"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "minted": {
                    "summary": "Key minted — plaintext shown once",
                    "value": {
                      "data": {
                        "id": "key_1042",
                        "tenantId": "acme",
                        "prefix": "osk_acme_8f3a",
                        "label": "Production key",
                        "scopes": [
                          "customers:read",
                          "connections:read"
                        ],
                        "createdAt": 1768469400000,
                        "lastUsedAt": null,
                        "revokedAt": null,
                        "plaintext": "osk_acme_8f3a2b9c4d5e6f7a8b9c0d1e2f3a4b5c"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Validation failed",
                    "value": {
                      "error": "Request validation failed.",
                      "code": "invalid_request"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Missing or invalid token",
                    "value": {
                      "error": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Insufficient role",
                    "value": {
                      "error": "Forbidden"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/api-keys/{id}/rotate": {
      "post": {
        "operationId": "api-keys.rotate",
        "summary": "Rotate a tenant API key (replacement plaintext returned once)",
        "tags": [
          "api-keys"
        ],
        "description": "Mint a replacement key with the same tenant, label, scopes and mode, and schedule the old key’s revocation after a grace window (default 24h) in which both keys work — no downtime gap while the new key is rolled out. Admin role required. The response includes the replacement’s plaintext **once**. Returns `404` when the key does not exist, is revoked or expired, or was already rotated inside its grace window. Writes an `api_key.rotate` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RotateApiKeyBody"
              }
            }
          },
          "description": "Request body to rotate a tenant API key."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ApiKeyRotate"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/api-keys/{id}": {
      "delete": {
        "operationId": "api-keys.delete",
        "summary": "Revoke a tenant API key",
        "tags": [
          "api-keys"
        ],
        "description": "Permanently revoke a tenant API key by id, taking effect immediately. Admin role required. Returns `404` if no key matches the id. Writes an `api_key.revoke` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/issuers": {
      "get": {
        "operationId": "oauth-clients.listIssuers",
        "summary": "List registered identity providers",
        "tags": [
          "oauth-clients"
        ],
        "description": "Every identity provider whose OIDC bearer tokens this deployment will accept on `/v1/*`. Operator role or higher — reading which service accounts can reach the deployment does not require the ability to add one.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OAuthIssuer"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "oauth-clients.createIssuer",
        "summary": "Register an identity provider",
        "tags": [
          "oauth-clients"
        ],
        "description": "Admin only. Audience is required: without it every token the issuer ever minted for any application would be accepted here.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOAuthIssuerBody"
              }
            }
          },
          "description": "Register an identity provider whose tokens the developer API accepts."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OAuthIssuer"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/readiness": {
      "get": {
        "operationId": "oauth-clients.readiness",
        "summary": "Whether OIDC bearer auth could admit anybody",
        "tags": [
          "oauth-clients"
        ],
        "description": "Checked before allowing `auth.dev_api_keys_enabled` to be switched off, so that change cannot lock every developer out of a running deployment. Ready means an issuer is enabled, can admit somebody, and has already verified a real token.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OAuthReadiness"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/presets": {
      "get": {
        "operationId": "oauth-clients.listPresets",
        "summary": "Claim-name defaults for known identity providers",
        "tags": [
          "oauth-clients"
        ],
        "description": "Keycloak, Auth0, Okta and Entra ID name the subject and scope claims differently. These are the defaults the admin form seeds from; the verifier itself is identical for every issuer.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OAuthPreset"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/issuers/{id}": {
      "get": {
        "operationId": "oauth-clients.getIssuer",
        "summary": "Get one issuer with its clients and scope rules",
        "tags": [
          "oauth-clients"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OAuthIssuerDetail"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "oauth-clients.updateIssuer",
        "summary": "Update an identity provider",
        "tags": [
          "oauth-clients"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateOAuthIssuerBody"
              }
            }
          },
          "description": "Fields to change. The merged row is validated, not the patch — switching to external authority without naming a tenant claim is refused here rather than failing open at request time."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OAuthIssuer"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "oauth-clients.deleteIssuer",
        "summary": "Delete an identity provider",
        "tags": [
          "oauth-clients"
        ],
        "description": "Removes the issuer along with its registered clients and scope rules. Tokens from it stop being accepted immediately.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/discover": {
      "post": {
        "operationId": "oauth-clients.discover",
        "summary": "Read an issuer discovery document",
        "tags": [
          "oauth-clients"
        ],
        "description": "Fetches `{issuer}/.well-known/openid-configuration` and reports the signing-key endpoint, without saving anything, so an operator can check a URL before committing to it. The document's own issuer must match what was typed — otherwise a misconfigured or hostile endpoint could point the deployment at somebody else's signing keys.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DiscoverOAuthIssuerBody"
              }
            }
          },
          "description": "Read an issuer's OpenID discovery document without saving anything."
        },
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OAuthDiscovery"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/issuers/{id}/clients": {
      "post": {
        "operationId": "oauth-clients.createClient",
        "summary": "Register a service account",
        "tags": [
          "oauth-clients"
        ],
        "description": "Binds a subject from this issuer to a tenant and a scope set. Deleting the row later cuts off a still-valid token immediately, which is what registry authority buys over reading scopes from the token.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOAuthClientBody"
              }
            }
          },
          "description": "Register a service account against an issuer."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OAuthClient"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/clients/{id}": {
      "delete": {
        "operationId": "oauth-clients.revokeClient",
        "summary": "Revoke a service account",
        "tags": [
          "oauth-clients"
        ],
        "description": "Takes effect on the next request, mid-token: the client row is consulted on every call, so a revoked account stops working before its token expires.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/issuers/{id}/rules": {
      "post": {
        "operationId": "oauth-clients.createScopeRule",
        "summary": "Add a scope-mapping rule",
        "tags": [
          "oauth-clients"
        ],
        "description": "With no rules the token's scope claim passes through verbatim. Once any rule exists, only mapped values survive — an unmapped one is dropped rather than passed through raw.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOAuthScopeRuleBody"
              }
            }
          },
          "description": "Map one of the IdP's scope values onto an OpenSteward scope."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OAuthScopeRule"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/oauth/rules/{id}": {
      "delete": {
        "operationId": "oauth-clients.deleteScopeRule",
        "summary": "Delete a scope-mapping rule",
        "tags": [
          "oauth-clients"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/end-user-tokens": {
      "get": {
        "operationId": "end-user-tokens.list",
        "summary": "List per-end-user MCP tokens",
        "tags": [
          "end-user-tokens"
        ],
        "description": "List MCP tokens scoped to individual end-users, optionally filtered by `endUserId` or `tenantId`. Operator role or higher. Returns token metadata only; plaintext secrets are never included.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "endUserId"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "tenantId"
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EndUserToken"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "end-user-tokens.create",
        "summary": "Mint a per-end-user MCP token",
        "tags": [
          "end-user-tokens"
        ],
        "description": "Mint an MCP token scoped to a single end-user. Operator role or higher. The response includes the plaintext token **once** — it cannot be retrieved again. Returns `400` if `endUserId` or `tenantId` is missing. Writes an `end_user_token.mint` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MintEndUserTokenBody"
              }
            }
          },
          "description": "Request body to mint an API token scoped to a single end-user."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EndUserTokenMint"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/end-user-tokens/{id}": {
      "delete": {
        "operationId": "end-user-tokens.delete",
        "summary": "Revoke a per-end-user MCP token",
        "tags": [
          "end-user-tokens"
        ],
        "description": "Revoke a per-end-user MCP token by id, effective immediately. Operator role or higher. Returns `404` if no token matches the id. Writes an `end_user_token.revoke` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhook-subscriptions": {
      "get": {
        "operationId": "webhook-subs.list",
        "summary": "List tenant webhook subscriptions",
        "tags": [
          "webhook-subs"
        ],
        "description": "List webhook subscriptions (outbound delivery targets for `customer.*` and `connect_link.*` events), optionally filtered by `tenantId` and by a `search` over the label and URL. Operator role or higher. Signing secrets are not included.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "tenantId"
          },
          {
            "schema": {
              "description": "Case-insensitive substring match over the subscription label and URL. Applied server-side over the whole set, so a match is found regardless of where the row sits in the list.",
              "example": "billing",
              "type": "string"
            },
            "in": "query",
            "name": "search",
            "description": "Case-insensitive substring match over the subscription label and URL. Applied server-side over the whole set, so a match is found regardless of where the row sits in the list."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookSubscription"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "webhook-subs.create",
        "summary": "Create a webhook subscription (secret returned once)",
        "tags": [
          "webhook-subs"
        ],
        "description": "Create a webhook subscription that delivers events to the given URL. Admin role required. The response includes the signing secret **once** — it is not stored in retrievable form and cannot be fetched again. Returns `400` if `tenantId` or `url` is missing. Writes a `webhook_sub.create` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWebhookSubscriptionBody"
              }
            }
          },
          "description": "Request body to create a webhook subscription. The signing secret is returned once in the response."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookSubscriptionWithSecret"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhook-subscriptions/{id}": {
      "delete": {
        "operationId": "webhook-subs.delete",
        "summary": "Delete a webhook subscription",
        "tags": [
          "webhook-subs"
        ],
        "description": "Delete a webhook subscription by id, stopping further deliveries immediately. Admin role required. Returns `404` if no subscription matches the id. Writes a `webhook_sub.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "webhook-subs.update",
        "summary": "Change a webhook subscription label, payload format or headers",
        "tags": [
          "webhook-subs"
        ],
        "description": "Change the label, and how deliveries are shaped and authenticated for this subscription. The URL and event list are immutable — recreate the subscription to change those. Headers are replaced wholesale rather than merged, so an operator can remove one; an empty object clears them. Header values are stored encrypted and never returned. Admin role required. Writes a `webhook_sub.update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateWebhookSubscriptionBody"
              }
            }
          },
          "description": "Request body to change a webhook subscription's label or delivery settings. The URL and event list are immutable."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookSubscription"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhook-subscriptions/{id}/paused": {
      "post": {
        "operationId": "webhook-subs.pause",
        "summary": "Pause or resume a webhook subscription",
        "tags": [
          "webhook-subs"
        ],
        "description": "Pause (default) or resume a subscription. A paused subscription is retained but receives no deliveries. Admin role required. Writes a `webhook_sub.pause` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "paused": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "paused": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "id",
                        "paused"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhook-subscriptions/{id}/test": {
      "post": {
        "operationId": "webhook-subs.test",
        "summary": "Send a test event to a webhook subscription",
        "tags": [
          "webhook-subs"
        ],
        "description": "Sends one synthetic `opensteward.test` event to this subscription, rendered in its own format, signed with its own secret and carrying its custom headers — so a destination can be proven to work without creating real data to trigger a real event. Nothing is queued and no delivery row is written. A receiver that rejects the payload is reported as `ok: false` with its status code rather than as an error. Works on a paused subscription. Admin role required. Writes a `webhook_sub.test` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookTestResult"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhook-subscriptions/{id}/rotate-secret": {
      "post": {
        "operationId": "webhook-subs.rotate-secret",
        "summary": "Rotate a webhook subscription signing secret",
        "tags": [
          "webhook-subs"
        ],
        "description": "Generate a NEW signing secret, replacing the old one. The plaintext is returned **once**. Admin role required. Writes a `webhook_sub.rotate_secret` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "secret": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "secret"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhook-subscriptions/{id}/deliveries": {
      "get": {
        "operationId": "webhook-subs.deliveries.list",
        "summary": "List deliveries for one subscription",
        "tags": [
          "webhook-subs"
        ],
        "description": "List recent delivery attempts for one subscription, optionally filtered by `status` (`pending`, `delivered`, `dead`), `eventType`, `eventId`, and ordered by `sort`/`dir`, capped by `limit`. Operator role or higher. Filters and sort apply before pagination, so `meta.total` reflects the filtered set and every page reflects the requested order. Useful for diagnosing failed or dead-lettered deliveries.",
        "parameters": [
          {
            "schema": {
              "description": "Filter by delivery status: `pending`, `delivered` or `dead`. An unrecognised value is ignored and no status filter is applied.",
              "example": "dead",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "status",
            "description": "Filter by delivery status: `pending`, `delivered` or `dead`. An unrecognised value is ignored and no status filter is applied."
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "limit"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "page"
          },
          {
            "schema": {
              "description": "Column to order by: one of `eventType`, `eventId`, `status`, `attempts`. An unrecognised value is ignored and the default order (most recent first) is used.",
              "example": "status",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "sort",
            "description": "Column to order by: one of `eventType`, `eventId`, `status`, `attempts`. An unrecognised value is ignored and the default order (most recent first) is used."
          },
          {
            "schema": {
              "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending.",
              "example": "desc",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "dir",
            "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the event type.",
              "example": "customer.created",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "eventType",
            "description": "Case-insensitive substring match against the event type."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the event id.",
              "example": "evt_123",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "eventId",
            "description": "Case-insensitive substring match against the event id."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookDelivery"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhook-subscriptions/{id}/deliveries/{deliveryId}/replay": {
      "post": {
        "operationId": "webhook-subs.deliveries.replay",
        "summary": "Replay a single webhook delivery",
        "tags": [
          "webhook-subs"
        ],
        "description": "Re-enqueue a single past delivery for redelivery, e.g. after the receiver was down. Admin role required. Responds `202 Accepted` with the queued delivery, or `404` if the subscription or delivery is not found. Writes a `webhook_delivery.replay` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "deliveryId",
            "required": true
          }
        ],
        "responses": {
          "202": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookDelivery"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sync-jobs": {
      "get": {
        "operationId": "sync-jobs.list",
        "summary": "List sync jobs",
        "tags": [
          "sync-jobs"
        ],
        "description": "List data-sync jobs, optionally filtered by `vertical`, `connection_id`, `status`, `platform`, `tenant_id`, `id` and `connection_id_contains`, ordered by `sort`/`dir`, and paged with `page`/`limit`. `meta.total` is the number of rows matching the filter across the whole deployment — a real count, so a caller can page through every one of them. A tenant-restricted caller sees only jobs for its granted tenants. Any authenticated operator.",
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/Vertical"
            },
            "in": "query",
            "name": "vertical"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "connection_id"
          },
          {
            "schema": {
              "$ref": "#/components/schemas/SyncJobStatus"
            },
            "in": "query",
            "name": "status"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "limit"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "page"
          },
          {
            "schema": {
              "description": "Column to order by: one of `vertical`, `platform`, `connection`, `tenant`, `status`, `created`. An unrecognised value is ignored and the default order (newest first) is used.",
              "example": "status",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "sort",
            "description": "Column to order by: one of `vertical`, `platform`, `connection`, `tenant`, `status`, `created`. An unrecognised value is ignored and the default order (newest first) is used."
          },
          {
            "schema": {
              "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending.",
              "example": "desc",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "dir",
            "description": "Sort direction: `asc` or `desc`. Any other value (including omitted) is ascending."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the platform slug.",
              "example": "fortnox",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "platform",
            "description": "Case-insensitive substring match against the platform slug."
          },
          {
            "schema": {
              "description": "Exact match against the connection's owning tenant id.",
              "example": "acme",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "tenant_id",
            "description": "Exact match against the connection's owning tenant id."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the sync job id.",
              "example": "9f8e7d6c",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "id",
            "description": "Case-insensitive substring match against the sync job id."
          },
          {
            "schema": {
              "description": "Case-insensitive substring match against the connection id. Distinct from `connection_id`, which is an exact match: the admin table filters on a prefix of the id its Connection cell shows.",
              "example": "9f8e7d6c",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "in": "query",
            "name": "connection_id_contains",
            "description": "Case-insensitive substring match against the connection id. Distinct from `connection_id`, which is an exact match: the admin table filters on a prefix of the id its Connection cell shows."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SyncJob"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "sync-jobs.create",
        "summary": "Enqueue a one-off sync job",
        "tags": [
          "sync-jobs"
        ],
        "description": "Enqueue a one-off data-sync job for a connection, with an optional completion `callback_url`. Operator role or higher. Responds `202 Accepted` with the queued job. Upstream refusals keep their own status: `409` when a sync is already running for the connection, `404` when the connection is unknown or the deployment runs in `passthrough` mode (no sync engine), `502` when integration-server cannot be reached. `400` if `connection_id` is missing. Writes a `sync_job.create` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSyncJobBody"
              }
            }
          },
          "description": "Request body to enqueue a data-sync job for a connection."
        },
        "responses": {
          "202": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SyncJob"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "500": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sync-jobs/{id}": {
      "get": {
        "operationId": "sync-jobs.get",
        "summary": "Read one sync job",
        "tags": [
          "sync-jobs"
        ],
        "description": "Read a single sync job by id, including its status and progress. Any authenticated operator. Returns `404` if the job does not exist.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SyncJob"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sync-jobs/{id}/cancel": {
      "post": {
        "operationId": "sync-jobs.cancel",
        "summary": "Cancel a running sync job",
        "tags": [
          "sync-jobs"
        ],
        "description": "Request cancellation of an in-flight sync job. Operator role or higher. Returns `404` if the job does not exist or is not in a cancelable state. Writes a `sync_job.cancel` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SyncJob"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/data-store/metrics": {
      "get": {
        "operationId": "sync-jobs.metrics",
        "summary": "Data-store metrics (resource counts, last sync timestamps, etc.)",
        "tags": [
          "sync-jobs"
        ],
        "description": "Return aggregate data-store metrics (resource counts, last-sync timestamps, and similar) for dashboards. Any authenticated operator; deployment-wide, so a tenant-restricted caller gets `403 SCOPE_RESTRICTED`. Responds with `data: null` when integration-server is unreachable so the UI can show an offline banner rather than erroring.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "anyOf": [
                        {
                          "$ref": "#/components/schemas/DataStoreMetrics"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/scope-groups": {
      "get": {
        "operationId": "scope-groups.list",
        "summary": "List scope groups",
        "tags": [
          "scope-groups"
        ],
        "description": "List named scope groups (reusable bundles of platform permissions), optionally filtered by `vertical` and/or `platform`. Any authenticated operator.",
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/Vertical"
            },
            "in": "query",
            "name": "vertical"
          },
          {
            "schema": {
              "type": "string",
              "description": "Adapter slug identifying an upstream platform, e.g. `fortnox`. See GET /api/platforms.",
              "example": "fortnox"
            },
            "in": "query",
            "name": "platform"
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ScopeGroup"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "scope-groups.create",
        "summary": "Create a scope group",
        "tags": [
          "scope-groups"
        ],
        "description": "Create a named scope group for a vertical/platform. Operator role or higher. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. Scopes may be supplied as an array or a delimited string and are normalised to a deduped array. Returns `400` if `vertical`, `platform`, `name`, or a non-empty scope set is missing, and `409` if a group with that name already exists for the platform. Writes a `scope_group.create` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateScopeGroupBody"
              }
            }
          },
          "description": "Request body to create a named scope group."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ScopeGroup"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "500": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/scope-groups/{id}": {
      "put": {
        "operationId": "scope-groups.update",
        "summary": "Update a scope group",
        "tags": [
          "scope-groups"
        ],
        "description": "Update a scope group's name and/or scopes; omitted fields are left unchanged. Operator role or higher. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. Returns `400` for a non-numeric id and `404` if the group does not exist. Writes a `scope_group.update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateScopeGroupBody"
              }
            }
          },
          "description": "Request body to update a scope group; omitted fields are left unchanged."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ScopeGroup"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "scope-groups.delete",
        "summary": "Delete a scope group",
        "tags": [
          "scope-groups"
        ],
        "description": "Delete a scope group by id. Operator role or higher. Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. Returns `400` for a non-numeric id and `404` if the group does not exist. Writes a `scope_group.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/connect-link-templates": {
      "get": {
        "operationId": "connect-link-templates.list",
        "summary": "List Connect Link templates",
        "tags": [
          "connect-link-templates"
        ],
        "description": "List Connect Link templates (reusable presets that define what a generated link lets a customer connect), optionally filtered by `tenantId`. Any authenticated operator.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "tenantId"
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ConnectLinkTemplate"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "connect-link-templates.create",
        "summary": "Create a Connect Link template",
        "tags": [
          "connect-link-templates"
        ],
        "description": "Create a Connect Link template defining the link mode, allowed verticals/platforms, scope group, expiry, and redirect for links generated from it. Operator role or higher. Returns `400` if `tenantId`/`name` is missing or `linkMode` is invalid, and `409` if a template with that name already exists for the tenant. Writes a `connect_link_template.create` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConnectLinkTemplateBody"
              },
              "examples": {
                "pinned": {
                  "summary": "Pinned — adapter pre-selected, customer has nothing to pick",
                  "value": {
                    "tenantId": "acme",
                    "name": "Acme onboarding",
                    "description": "Onboarding link for Acme Industries.",
                    "linkMode": "pinned",
                    "allowedVerticals": [
                      "accounting"
                    ],
                    "allowedPlatforms": [
                      {
                        "vertical": "accounting",
                        "slug": "xero"
                      }
                    ],
                    "scopeGroupId": 7,
                    "expiryDays": 7,
                    "oneTimeOnly": false,
                    "redirectUrl": "https://app.acme.example/return"
                  }
                },
                "customer-picks": {
                  "summary": "Customer-picks — customer chooses from an allow-list",
                  "value": {
                    "tenantId": "acme",
                    "name": "Acme onboarding",
                    "description": "Customer chooses which accounting platform to connect.",
                    "linkMode": "customer-picks-adapter",
                    "allowedVerticals": [
                      "accounting"
                    ],
                    "allowedPlatforms": [
                      {
                        "vertical": "accounting",
                        "slug": "xero"
                      },
                      {
                        "vertical": "accounting",
                        "slug": "quickbooks"
                      }
                    ],
                    "scopeGroupId": 7,
                    "expiryDays": 7,
                    "oneTimeOnly": false,
                    "redirectUrl": "https://app.acme.example/return"
                  }
                },
                "self-register": {
                  "summary": "Self-register — open onboarding, no allow-list",
                  "value": {
                    "tenantId": "acme",
                    "name": "Acme onboarding",
                    "description": "Open self-registration link.",
                    "linkMode": "self-register",
                    "allowedVerticals": [],
                    "allowedPlatforms": [],
                    "expiryDays": 7,
                    "oneTimeOnly": false,
                    "redirectUrl": "https://app.acme.example/return"
                  }
                }
              }
            }
          },
          "description": "Request body to create a connect-link template."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ConnectLinkTemplate"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "pinned": {
                    "summary": "Pinned template created",
                    "value": {
                      "data": {
                        "id": 7,
                        "tenantId": "acme",
                        "name": "Acme onboarding",
                        "description": "Onboarding link for Acme Industries.",
                        "linkMode": "pinned",
                        "allowedPlatforms": [
                          {
                            "vertical": "accounting",
                            "slug": "xero"
                          }
                        ],
                        "allowedVerticals": [
                          "accounting"
                        ],
                        "scopeGroupId": 7,
                        "expiryDays": 7,
                        "oneTimeOnly": false,
                        "redirectUrl": "https://app.acme.example/return",
                        "createdAt": 1768469400000,
                        "createdBy": "usr_olivia"
                      }
                    }
                  },
                  "customer-picks": {
                    "summary": "Customer-picks template created",
                    "value": {
                      "data": {
                        "id": 7,
                        "tenantId": "acme",
                        "name": "Acme onboarding",
                        "description": "Customer chooses which accounting platform to connect.",
                        "linkMode": "customer-picks-adapter",
                        "allowedPlatforms": [
                          {
                            "vertical": "accounting",
                            "slug": "xero"
                          },
                          {
                            "vertical": "accounting",
                            "slug": "quickbooks"
                          }
                        ],
                        "allowedVerticals": [
                          "accounting"
                        ],
                        "scopeGroupId": 7,
                        "expiryDays": 7,
                        "oneTimeOnly": false,
                        "redirectUrl": "https://app.acme.example/return",
                        "createdAt": 1768469400000,
                        "createdBy": "usr_olivia"
                      }
                    }
                  },
                  "self-register": {
                    "summary": "Self-register template created",
                    "value": {
                      "data": {
                        "id": 7,
                        "tenantId": "acme",
                        "name": "Acme onboarding",
                        "description": "Open self-registration link.",
                        "linkMode": "self-register",
                        "allowedPlatforms": [],
                        "allowedVerticals": [],
                        "scopeGroupId": 7,
                        "expiryDays": 7,
                        "oneTimeOnly": false,
                        "redirectUrl": "https://app.acme.example/return",
                        "createdAt": 1768469400000,
                        "createdBy": "usr_olivia"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Validation failed",
                    "value": {
                      "error": "Request validation failed.",
                      "code": "invalid_request"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Missing or invalid token",
                    "value": {
                      "error": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Insufficient role",
                    "value": {
                      "error": "Forbidden"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "default": {
                    "summary": "Conflict",
                    "value": {
                      "error": "Already exists"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/connect-link-templates/{id}": {
      "get": {
        "operationId": "connect-link-templates.get",
        "summary": "Read one Connect Link template",
        "tags": [
          "connect-link-templates"
        ],
        "description": "Read a single Connect Link template by id. Any authenticated operator. Returns `400` for a non-numeric id and `404` if the template does not exist.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ConnectLinkTemplate"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "connect-link-templates.update",
        "summary": "Update a Connect Link template",
        "tags": [
          "connect-link-templates"
        ],
        "description": "Update a Connect Link template; omitted fields are left unchanged. Operator role or higher. Returns `400` for a non-numeric id or invalid `linkMode`, and `404` if the template does not exist. Writes a `connect_link_template.update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateConnectLinkTemplateBody"
              }
            }
          },
          "description": "Request body to update a connect-link template; omitted fields are left unchanged."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ConnectLinkTemplate"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "connect-link-templates.delete",
        "summary": "Delete a Connect Link template",
        "tags": [
          "connect-link-templates"
        ],
        "description": "Delete a Connect Link template by id. Operator role or higher. Returns `400` for a non-numeric id and `404` if the template does not exist. Writes a `connect_link_template.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/tenant-domains/public": {
      "get": {
        "operationId": "tenant-domains.get-public",
        "summary": "Public domain→tenant map (no auth)",
        "tags": [
          "tenants"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TenantDomainMapEntry"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/tenants": {
      "get": {
        "operationId": "tenants.list",
        "summary": "List tenants",
        "tags": [
          "tenants"
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Tenant"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "tenants.create",
        "summary": "Create a tenant",
        "tags": [
          "tenants"
        ],
        "description": "Register a tenant. Operator role. 403 `SCOPE_RESTRICTED` for a tenant-restricted caller; 403 `LICENSE_LIMIT_EXCEEDED` (with `limitKey: 'tenants'`, `limit` and `used`) when the license's tenant limit, which counts `default`, is reached; 409 when the id already exists. Existing tenants are never removed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTenantBody"
              }
            }
          },
          "description": "Request body to register a new tenant."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Tenant"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/tenants/{id}": {
      "put": {
        "operationId": "tenants.update",
        "summary": "Rename a tenant",
        "tags": [
          "tenants"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateTenantBody"
              }
            }
          },
          "description": "Request body to rename a tenant."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Tenant"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "tenants.delete",
        "summary": "Delete a tenant (not the default; must have no domains)",
        "tags": [
          "tenants"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/tenant-domains": {
      "get": {
        "operationId": "tenant-domains.list",
        "summary": "List all custom domains",
        "tags": [
          "tenants"
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TenantDomain"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "tenant-domains.create",
        "summary": "Attach a custom domain to a tenant",
        "tags": [
          "tenants"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddTenantDomainBody"
              }
            }
          },
          "description": "Request body to attach a custom domain to a tenant."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TenantDomain"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/tenant-domains/{domain}": {
      "delete": {
        "operationId": "tenant-domains.delete",
        "summary": "Detach a custom domain",
        "tags": [
          "tenants"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "domain",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/dashboard-tasks/dismissals": {
      "get": {
        "operationId": "dashboard-tasks.list-dismissals",
        "summary": "List cleared dashboard tasks",
        "tags": [
          "dashboard-tasks"
        ],
        "description": "Every dashboard task that has been cleared, with the fingerprint it was cleared at. The dashboard hides a task only when both the key and the fingerprint match. Any authenticated operator. A tenant-restricted user sees only the keys whose connection or sync job is inside their scope.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DashboardDismissal"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "dashboard-tasks.dismiss",
        "summary": "Clear dashboard tasks",
        "tags": [
          "dashboard-tasks"
        ],
        "description": "Clear 1..50 dashboard tasks deployment-wide. Also acknowledges the matching unacknowledged notifications (`credential_expired` for `conn:expired:*`, `platform_credentials_invalid` for `platform:creds:*`), and the health poller will not re-raise them while the fingerprint is unchanged. Operator role or higher; Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. `platform:creds:*` and `wizard:*` keys need the admin role, and one such key in the batch makes the whole request `403` with nothing stored. Writes a `dashboard_task.dismiss` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DismissDashboardTasksBody"
              }
            }
          },
          "description": "Request body to clear dashboard tasks."
        },
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/dashboard-tasks/dismissals/{key}": {
      "delete": {
        "operationId": "dashboard-tasks.undismiss",
        "summary": "Un-clear a dashboard task",
        "tags": [
          "dashboard-tasks"
        ],
        "description": "Remove one clear so the task shows on the dashboard again (the Undo behind a clear). Operator role or higher; Refused (`403 SCOPE_RESTRICTED`) for a user restricted to specific tenants: it affects every tenant. `platform:creds:*` and `wizard:*` keys need the admin role (`403` otherwise). Returns `404` when the key was not cleared. Writes a `dashboard_task.undismiss` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^(conn:expired|platform:creds|sync:failed|refresh:failing|wizard):[A-Za-z0-9_.:/-]{1,300}$",
              "description": "Task key to un-clear (URL-encode it: keys contain `:` and may contain `/`).",
              "example": "conn:expired:conn_1042"
            },
            "in": "path",
            "name": "key",
            "required": true,
            "description": "Task key to un-clear (URL-encode it: keys contain `:` and may contain `/`)."
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/runtime-settings": {
      "get": {
        "operationId": "runtime-settings.list",
        "summary": "List runtime settings",
        "tags": [
          "runtime-settings"
        ],
        "description": "List all runtime settings (tunables that can change without a redeploy) with their current values. Any authenticated operator may read — so the setup wizard can show the active mode — but only admins may change them.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RuntimeSetting"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/runtime-settings/{key}": {
      "patch": {
        "operationId": "runtime-settings.update",
        "summary": "Update a runtime setting value",
        "tags": [
          "runtime-settings"
        ],
        "description": "Update one runtime setting; the value type is validated against the seeded key. Admin role required. Returns `400` if the body `key` does not match the path key or the value fails validation, and `409` (break-glass) if disabling local login would leave no password-usable local admin. Takes effect promptly via cache invalidation and writes a `runtime_setting.update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateRuntimeSettingBody"
              }
            }
          },
          "description": "PATCH body for /api/runtime-settings/{key}. Discriminated on `key`, one branch per value shape, so the `value` field is typed as number / boolean / string / a closed vocabulary / unknown for JSON."
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "rate_limit.api_key.per_minute",
                "rate_limit.api_key.window_ms",
                "rate_limit.mcp_tenant.per_minute",
                "rate_limit.mcp_end_user.per_minute",
                "rate_limit.connect_link.per_minute",
                "features.mcp_enabled",
                "features.end_user_mode_enabled",
                "features.test_mode_enabled",
                "connect_link.default_expiry_hours",
                "connect_link.one_time_default",
                "auth.local_login_enabled",
                "auth.break_glass_user_id",
                "auth.dev_api_keys_enabled",
                "auth.dev_oauth_enabled",
                "auth.sandbox_self_serve_enabled",
                "data_store.raw_payload.payments",
                "data_store.raw_payload.accounting",
                "data_store.sync.default_interval_minutes",
                "data_store.sync.scheduler_enabled",
                "data_access.mask_financial",
                "webhooks.delivery_retention_days",
                "webhooks.inbound_event_retention_days",
                "audit_log.retention_days",
                "openapi.servers.scheme",
                "openapi.servers.host",
                "openapi.servers.port",
                "openapi.servers.version",
                "logos.source",
                "logos.brandfetch_client_id",
                "logos.fetch_delay_ms",
                "logos.job_retention_days",
                "logos.fetch_referer"
              ],
              "description": "Runtime-setting key — one of the seeded inventory."
            },
            "in": "path",
            "name": "key",
            "required": true,
            "description": "Runtime-setting key — one of the seeded inventory."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RuntimeSetting"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "runtime-settings.reset",
        "summary": "Reset a runtime setting to its seeded default",
        "tags": [
          "runtime-settings"
        ],
        "description": "Reset a runtime setting back to its seeded default value. Admin role required. Returns `404` if the key is unknown. Writes a `runtime_setting.reset` audit entry and invalidates the downstream settings cache.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "rate_limit.api_key.per_minute",
                "rate_limit.api_key.window_ms",
                "rate_limit.mcp_tenant.per_minute",
                "rate_limit.mcp_end_user.per_minute",
                "rate_limit.connect_link.per_minute",
                "features.mcp_enabled",
                "features.end_user_mode_enabled",
                "features.test_mode_enabled",
                "connect_link.default_expiry_hours",
                "connect_link.one_time_default",
                "auth.local_login_enabled",
                "auth.break_glass_user_id",
                "auth.dev_api_keys_enabled",
                "auth.dev_oauth_enabled",
                "auth.sandbox_self_serve_enabled",
                "data_store.raw_payload.payments",
                "data_store.raw_payload.accounting",
                "data_store.sync.default_interval_minutes",
                "data_store.sync.scheduler_enabled",
                "data_access.mask_financial",
                "webhooks.delivery_retention_days",
                "webhooks.inbound_event_retention_days",
                "audit_log.retention_days",
                "openapi.servers.scheme",
                "openapi.servers.host",
                "openapi.servers.port",
                "openapi.servers.version",
                "logos.source",
                "logos.brandfetch_client_id",
                "logos.fetch_delay_ms",
                "logos.job_retention_days",
                "logos.fetch_referer"
              ],
              "description": "Runtime-setting key — one of the seeded inventory."
            },
            "in": "path",
            "name": "key",
            "required": true,
            "description": "Runtime-setting key — one of the seeded inventory."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RuntimeSetting"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/logo-fetch": {
      "post": {
        "operationId": "logo-fetch.start",
        "summary": "Start a platform logo fetch",
        "tags": [
          "logos"
        ],
        "description": "Queue a background job that downloads platform logos from Brandfetch and stores them in the admin database. Returns 202 with the queued job. A full catalog run takes tens of minutes; poll the job for progress. Only one fetch may run at a time.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "force": {
                    "description": "Refetch logos that are already stored instead of skipping them.",
                    "example": false,
                    "type": "boolean"
                  },
                  "vertical": {
                    "description": "Limit the fetch to one vertical.",
                    "example": "accounting",
                    "type": "string"
                  },
                  "slug": {
                    "description": "Limit the fetch to a single platform.",
                    "example": "xero",
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LogoFetchJob"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "logo-fetch.list",
        "summary": "List logo-fetch jobs",
        "tags": [
          "logos"
        ],
        "description": "Recent logo-fetch jobs, newest first. Any authenticated operator may watch a running fetch.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LogoFetchJob"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/logo-fetch/{id}": {
      "get": {
        "operationId": "logo-fetch.get",
        "summary": "Get a logo-fetch job",
        "tags": [
          "logos"
        ],
        "description": "Fetch one logo-fetch job, including its per-vertical progress counters.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Logo-fetch job identifier.",
              "example": "lfj_01HQ8ZK"
            },
            "in": "path",
            "name": "id",
            "required": true,
            "description": "Logo-fetch job identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LogoFetchJob"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/logo-fetch/{id}/cancel": {
      "post": {
        "operationId": "logo-fetch.cancel",
        "summary": "Cancel a logo-fetch job",
        "tags": [
          "logos"
        ],
        "description": "Ask a logo-fetch job to stop. A queued job is cancelled immediately (200). A running job moves to `cancelling` and stops at its next checkpoint (202) — cancellation is cooperative because the request usually lands on a different replica than the one running the job. Logos already fetched are kept.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Logo-fetch job identifier.",
              "example": "lfj_01HQ8ZK"
            },
            "in": "path",
            "name": "id",
            "required": true,
            "description": "Logo-fetch job identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LogoFetchJob"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "202": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LogoFetchJob"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/logos/status": {
      "get": {
        "operationId": "logos.status",
        "summary": "Stored logo statistics",
        "tags": [
          "logos"
        ],
        "description": "How many platform logos this deployment has stored, their total size, and when the newest was fetched.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LogoStatus"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/logos": {
      "delete": {
        "operationId": "logos.purge",
        "summary": "Delete every stored logo",
        "tags": [
          "logos"
        ],
        "description": "Remove all stored platform logos. The catalog falls back to monogram tiles immediately. Provided because storing logos is caching under Brandfetch’s terms, so an operator needs a way to undo it.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LogoPurgeResult"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-providers": {
      "get": {
        "operationId": "identity-providers.list",
        "summary": "List configured identity providers",
        "tags": [
          "identity-providers"
        ],
        "description": "List the configured SSO identity providers (SAML/OIDC) and their enabled state. Admin role required. Secrets are not returned.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/IdentityProvider"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "identity-providers.create",
        "summary": "Create an identity provider",
        "tags": [
          "identity-providers"
        ],
        "description": "Register a new SSO identity provider with its protocol-specific config. Admin role required. Returns `400` if the body or protocol config is invalid, and `409` if the slug is already taken. Writes an `sso.provider.create` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateIdentityProviderBody"
              }
            }
          },
          "description": "Create an identity provider. Body is keyed by `protocol` — OIDC, SAML, and LDAP each pin the per-protocol config shape."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/IdentityProvider"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-providers/{id}": {
      "get": {
        "operationId": "identity-providers.get",
        "summary": "Read one identity provider",
        "tags": [
          "identity-providers"
        ],
        "description": "Read a single identity provider's configuration by id (secrets redacted). Admin role required. Returns `404` if no provider matches the id.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/IdentityProvider"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "identity-providers.update",
        "summary": "Update an identity provider",
        "tags": [
          "identity-providers"
        ],
        "description": "Update an identity provider's settings, config, or secret; omitted fields are left unchanged. Admin role required. Returns `404` if the provider is missing, `400` if the protocol config is invalid, and `409` if changing the slug collides with another provider — or if the stored secret bundle cannot be decrypted with the current STORE_SECRET, in which case nothing is written, because merging into an unreadable bundle would discard every secret not resent. Recover by restoring the previous STORE_SECRET (or running rotate-store-secret); or resend every secret with `replaceUnreadableSecret` to replace the bundle outright. Writes an `sso.provider.update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateIdentityProviderBody"
              }
            }
          },
          "description": "Request body to update an identity provider; omitted fields are left unchanged. Protocol is immutable."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/IdentityProvider"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "identity-providers.delete",
        "summary": "Delete an identity provider",
        "tags": [
          "identity-providers"
        ],
        "description": "Delete an identity provider, disabling SSO logins through it. Admin role required. Returns `404` if no provider matches the id. Writes an `sso.provider.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-providers/{id}/metadata": {
      "get": {
        "operationId": "identity-providers.metadata",
        "summary": "SAML SP metadata XML (admin-only)",
        "tags": [
          "identity-providers"
        ],
        "description": "Return this service's SAML service-provider metadata as `application/xml`, to hand to the IdP during setup (advertises the ACS URL and, when configured, the SP signing certificate). Admin role required. Returns `404` if the provider does not exist or is not a SAML provider.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-providers/{id}/role-mappings": {
      "get": {
        "operationId": "identity-providers.role-mappings.list",
        "summary": "List a provider's role-mapping rules",
        "tags": [
          "identity-providers"
        ],
        "description": "List the role-mapping rules for one provider — the rules that translate IdP claims/groups into local roles on SSO login. Admin role required. Returns `404` if the provider does not exist.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RoleMappingRule"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "identity-providers.role-mappings.create",
        "summary": "Create a role-mapping rule",
        "tags": [
          "identity-providers"
        ],
        "description": "Add a role-mapping rule to a provider, mapping an IdP claim/group to a local role — a built-in `role`, or any role (built-in or custom) by `roleId`. Admin role required. Returns `404` if the provider does not exist, `400` if the rule body is invalid or `roleId` is unknown, and `403` if the role grants a permission or base role you do not hold. Writes an `sso.role_mapping.create` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRoleMappingRuleBody"
              }
            }
          },
          "description": "Request body to create a role-mapping rule for an identity provider."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoleMappingRule"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-providers/{id}/role-mappings/{ruleId}": {
      "delete": {
        "operationId": "identity-providers.role-mappings.delete",
        "summary": "Delete a role-mapping rule",
        "tags": [
          "identity-providers"
        ],
        "description": "Delete a single role-mapping rule from a provider. Admin role required. Returns `404` if the rule (or provider) does not exist. Writes an `sso.role_mapping.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "ruleId",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-providers/{id}/scope-rules": {
      "get": {
        "operationId": "identity-providers.scope-rules.list",
        "summary": "List a provider's scope-mapping rules",
        "tags": [
          "identity-providers"
        ],
        "description": "List the scope-mapping rules for one provider — the rules that grant tenant scope from IdP claims/groups on SSO login. Every matching rule applies (the tenants are unioned); when none match, the provider default scope applies. Admin role and `users:manage` required. Returns `404` if the provider does not exist.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ScopeMappingRule"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "identity-providers.scope-rules.create",
        "summary": "Create a scope-mapping rule",
        "tags": [
          "identity-providers"
        ],
        "description": "Add a scope-mapping rule: users whose claim matches may see the listed tenants (`[\"*\"]` = every tenant), optionally only some verticals. Applied on each SSO login and SCIM group change to users whose scope is IdP-owned (`scopeSource: idp`, the default for JIT and SCIM users). Admin role and `users:manage` required. Returns `404` if the provider does not exist, `400` for an invalid body or unknown tenant, and `403` when the rule grants tenants outside your own scope. Writes an `idp.scope_rule.create` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateScopeMappingRuleBody"
              }
            }
          },
          "description": "Request body to create a scope-mapping rule for an identity provider."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ScopeMappingRule"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-providers/{id}/scope-rules/{ruleId}": {
      "delete": {
        "operationId": "identity-providers.scope-rules.delete",
        "summary": "Delete a scope-mapping rule",
        "tags": [
          "identity-providers"
        ],
        "description": "Delete a single scope-mapping rule from a provider. Takes effect for each affected user at their next SSO login. Admin role and `users:manage` required. Returns `404` if the rule (or provider) does not exist. Writes an `idp.scope_rule.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "ruleId",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-providers/{id}/default-scope": {
      "patch": {
        "operationId": "identity-providers.default-scope.update",
        "summary": "Set a provider's default tenant scope",
        "tags": [
          "identity-providers"
        ],
        "description": "Set the scope SSO users of this provider get when no scope rule matches: `all` tenants (the default, and what every provider had before scope rules existed) or `restricted` to `tenantIds` (empty = no tenants). Admin role and `users:manage` required. Returns `404` if the provider does not exist, `400` for an unknown tenant, and `403` when the scope reaches beyond your own. Writes an `idp.default_scope.update` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateIdpDefaultScopeBody"
              }
            }
          },
          "description": "Request body to set an identity provider's default tenant scope."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/IdentityProvider"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-providers/{id}/scim-tokens": {
      "get": {
        "operationId": "identity-providers.scim-tokens.list",
        "summary": "List SCIM bearer tokens for a provider",
        "tags": [
          "identity-providers"
        ],
        "description": "List the SCIM bearer tokens issued for a provider (used by the IdP to provision/deprovision users via SCIM). Admin role required. Plaintext token values are not returned. Returns `404` if the provider does not exist.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ScimToken"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "identity-providers.scim-tokens.create",
        "summary": "Mint a SCIM bearer token (plaintext returned once)",
        "tags": [
          "identity-providers"
        ],
        "description": "Mint a new SCIM bearer token for a provider. Admin role required. The response includes the plaintext token **once** — it cannot be retrieved again. Returns `404` if the provider does not exist. Writes an `sso.scim_token.mint` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MintScimTokenBody"
              }
            }
          },
          "description": "Request body to mint a SCIM provisioning token for an identity provider."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ScimTokenMint"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-providers/{id}/scim-tokens/{tokenId}": {
      "delete": {
        "operationId": "identity-providers.scim-tokens.delete",
        "summary": "Revoke a SCIM bearer token",
        "tags": [
          "identity-providers"
        ],
        "description": "Revoke a SCIM bearer token by id, effective immediately. Admin role required. Returns `404` if no token matches the id. Writes an `sso.scim_token.revoke` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "tokenId",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sso/login-options": {
      "get": {
        "operationId": "sso.login-options",
        "summary": "Public list of enabled SSO providers + local-login flag",
        "tags": [
          "sso"
        ],
        "description": "Public, **unauthenticated** endpoint that returns the enabled SSO providers (no secrets) and whether the local password form should be shown. Consumed by the login page to render its sign-in options.",
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LoginOptions"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/sso/{slug}/login": {
      "get": {
        "operationId": "sso.login",
        "summary": "Begin an OIDC / SAML login redirect",
        "tags": [
          "sso"
        ],
        "description": "Begin an SSO login by redirecting (`302`) to the OIDC or SAML provider identified by `slug`; an optional `return_to` is preserved through the round-trip. Unauthenticated and rate-limited (10/min). Returns `404` if the provider is unknown or disabled, `400` if it does not support redirect login (e.g. LDAP), and `502` if initiation fails.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "return_to"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "slug",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "302": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sso/{slug}/callback": {
      "get": {
        "operationId": "sso.callback",
        "summary": "OIDC redirect-callback endpoint",
        "tags": [
          "sso"
        ],
        "description": "OIDC redirect-callback the provider sends the browser back to after authentication. Unauthenticated and rate-limited (10/min). Validates the `state`, provisions/maps the user, then `302`-redirects to the UI completion route with a one-time handoff code. Returns `400` for missing/invalid/expired state, `404` for an unknown provider, and `401` if authentication fails. Writes an `sso.login` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "state"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "slug",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "302": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sso/{slug}/acs": {
      "post": {
        "operationId": "sso.acs",
        "summary": "SAML Assertion Consumer Service (form-POST)",
        "tags": [
          "sso"
        ],
        "description": "SAML Assertion Consumer Service: the form-encoded `SAMLResponse` the IdP POSTs after authentication. Unauthenticated and rate-limited (10/min). Validates the assertion, provisions/maps the user, then `302`-redirects to the UI completion route with a one-time handoff code. Returns `400` if `SAMLResponse` is missing, `404` for a non-SAML/unknown provider, `500` if the IdP certificate is unconfigured, and `401` on validation failure. Writes an `sso.login` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SamlAcsBody"
              }
            }
          },
          "description": "Form body the IdP POSTs to the SAML Assertion Consumer Service endpoint."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "slug",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "302": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "500": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sso/{slug}/ldap-login": {
      "post": {
        "operationId": "sso.ldap-login",
        "summary": "LDAP direct username/password login → JWT",
        "tags": [
          "sso"
        ],
        "description": "Authenticate a username/password directly against an LDAP provider and return a JWT (no browser redirect). Unauthenticated and tightly rate-limited (5/min). Returns `400` if a credential is missing, `404` for an unknown/disabled/non-LDAP provider, `401` on invalid credentials, and `403` if JIT provisioning is disabled for a first-time user. Writes an `sso.login` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LdapLoginBody"
              }
            }
          },
          "description": "Credentials submitted to authenticate against an LDAP identity provider."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "slug",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sso/handoff/exchange": {
      "post": {
        "operationId": "sso.handoff.exchange",
        "summary": "Exchange a one-time SSO handoff code for a JWT",
        "tags": [
          "sso"
        ],
        "description": "Exchange the one-time handoff code issued at the end of an OIDC/SAML flow for a JWT. Called server-to-server by the admin UI; unauthenticated and rate-limited (30/min). The code is single-use — returns `400` if it is missing, already consumed, or expired.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SsoHandoffBody"
              }
            }
          },
          "description": "Body carrying the one-time SSO handoff code to exchange for a bearer token."
        },
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/scim/v2/ServiceProviderConfig": {
      "get": {
        "operationId": "scim.service-provider-config",
        "summary": "SCIM 2.0 ServiceProviderConfig discovery doc",
        "tags": [
          "scim"
        ],
        "description": "SCIM 2.0 `ServiceProviderConfig` discovery document advertising the supported features. Authenticated by a per-provider SCIM bearer token (not the admin JWT); returns `401` if the token is missing or invalid. Called by IdPs during SCIM setup.",
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          }
        }
      }
    },
    "/scim/v2/Users": {
      "get": {
        "operationId": "scim.users.list",
        "summary": "SCIM 2.0 Users list",
        "tags": [
          "scim"
        ],
        "description": "List SCIM Users provisioned through the calling provider, supporting `filter` (e.g. `userName eq`) and `startIndex`/`count` pagination per RFC 7644. Authenticated by the per-provider SCIM bearer token (`401` if invalid). Driven by the IdP, not the admin UI.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "filter"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "startIndex"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "count"
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "scim.users.create",
        "summary": "SCIM 2.0 User create (provision)",
        "tags": [
          "scim"
        ],
        "description": "Provision a new admin user from a SCIM User resource, creating the local account and identity link. Authenticated by the per-provider SCIM bearer token (`401` if invalid). The user's role is derived from group membership via the provider's role-mapping rules. Writes a SCIM provisioning audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScimResource"
              }
            }
          },
          "description": "A SCIM 2.0 resource (User or Group); an open object whose fields follow the SCIM schema for the endpoint."
        },
        "security": [],
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          }
        }
      }
    },
    "/scim/v2/Users/{id}": {
      "get": {
        "operationId": "scim.users.get",
        "summary": "SCIM 2.0 User read",
        "tags": [
          "scim"
        ],
        "description": "Read one SCIM User by id. Authenticated by the per-provider SCIM bearer token (`401` if invalid). Returns `404` if the user is not provisioned through this provider.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "scim.users.replace",
        "summary": "SCIM 2.0 User replace",
        "tags": [
          "scim"
        ],
        "description": "Replace a SCIM User resource (PUT). Authenticated by the per-provider SCIM bearer token (`401` if invalid). Returns `404` if the user is not provisioned through this provider. Setting `active: false` deprovisions the user, subject to the break-glass guard.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScimResource"
              }
            }
          },
          "description": "A SCIM 2.0 resource (User or Group); an open object whose fields follow the SCIM schema for the endpoint."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "scim.users.patch",
        "summary": "SCIM 2.0 User patch (PatchOp)",
        "tags": [
          "scim"
        ],
        "description": "Apply a SCIM `PatchOp` to a User (e.g. toggle `active` to deactivate). Authenticated by the per-provider SCIM bearer token (`401` if invalid). Returns `404` if the user is unknown; deactivation deprovisions the account, subject to the break-glass guard.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScimResource"
              }
            }
          },
          "description": "A SCIM 2.0 resource (User or Group); an open object whose fields follow the SCIM schema for the endpoint."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "scim.users.delete",
        "summary": "SCIM 2.0 User delete (deprovision)",
        "tags": [
          "scim"
        ],
        "description": "Deprovision (delete) a SCIM User, removing the local account and its identity links. Authenticated by the per-provider SCIM bearer token (`401` if invalid). Returns `409` if deletion would leave no break-glass admin. Writes an `sso.scim.deprovision` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          }
        }
      }
    },
    "/scim/v2/Groups": {
      "get": {
        "operationId": "scim.groups.list",
        "summary": "SCIM 2.0 Groups list",
        "tags": [
          "scim"
        ],
        "description": "List SCIM Groups for the calling provider, with optional `filter` support per RFC 7644. Authenticated by the per-provider SCIM bearer token (`401` if invalid). Group membership feeds the same role-mapping engine used at login.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "filter"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "startIndex"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "count"
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "scim.groups.create",
        "summary": "SCIM 2.0 Group create",
        "tags": [
          "scim"
        ],
        "description": "Create a SCIM Group for the calling provider. Authenticated by the per-provider SCIM bearer token (`401` if invalid). Membership changes recompute affected users' roles via the provider's role-mapping rules.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScimResource"
              }
            }
          },
          "description": "A SCIM 2.0 resource (User or Group); an open object whose fields follow the SCIM schema for the endpoint."
        },
        "security": [],
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          }
        }
      }
    },
    "/scim/v2/Groups/{id}": {
      "get": {
        "operationId": "scim.groups.get",
        "summary": "SCIM 2.0 Group read",
        "tags": [
          "scim"
        ],
        "description": "Read one SCIM Group by id, including its members. Authenticated by the per-provider SCIM bearer token (`401` if invalid). Returns `404` if the group does not exist for this provider.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "scim.groups.patch",
        "summary": "SCIM 2.0 Group patch",
        "tags": [
          "scim"
        ],
        "description": "Apply a SCIM `PatchOp` to a Group, typically to add or remove members. Authenticated by the per-provider SCIM bearer token (`401` if invalid). Returns `404` if the group is unknown; membership changes recompute affected users' roles.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScimResource"
              }
            }
          },
          "description": "A SCIM 2.0 resource (User or Group); an open object whose fields follow the SCIM schema for the endpoint."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimResource"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "scim.groups.delete",
        "summary": "SCIM 2.0 Group delete",
        "tags": [
          "scim"
        ],
        "description": "Delete a SCIM Group. Authenticated by the per-provider SCIM bearer token (`401` if invalid). Returns `404` if the group does not exist; removing it recomputes the roles of its former members.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          }
        }
      }
    },
    "/api/schema-status": {
      "get": {
        "operationId": "schema-status.list",
        "summary": "Per-namespace _schema_migrations rows for every reachable SQLite db",
        "tags": [
          "schema-status"
        ],
        "description": "Report the applied `_schema_migrations` rows for each SQLite database this admin-api can reach, grouped by namespace. Admin role required (diagnostic detail not exposed to operator/viewer). Developer diagnostics: migrations apply when each service starts and a failed one stops the boot, so a running service has applied its own. A missing db file is reported as an empty row set rather than an error.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SchemaStatusEntry"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/license": {
      "get": {
        "operationId": "license.get",
        "summary": "The deployment's license status",
        "tags": [
          "license"
        ],
        "description": "The license as integration-server evaluates it (state, who it is issued to, expiry, enabled features, limits and usage), as admin-api last read it — cached for a minute, served with `stale: true` while integration-server is not answering. Never contains the license token. Admin role required. 503 `LICENSE_STATUS_UNAVAILABLE` until integration-server has answered once; its message names `ADMIN_SECRET` when that is why.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/LicenseStatus"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "503": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/data/summary": {
      "get": {
        "operationId": "data.summary",
        "summary": "Summarise stored data per connection",
        "tags": [
          "data"
        ],
        "description": "List every connection in your tenant scope with the resource types the data store holds for it: record counts, the newest change and when each type was last fully synced. Requires `data:read`. Answers `409` (`DATA_STORE_DISABLED`) when the deployment runs in passthrough mode.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DataConnectionSummary"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/data/schema/{vertical}/{type}": {
      "get": {
        "operationId": "data.schema",
        "summary": "Describe a stored resource type",
        "tags": [
          "data"
        ],
        "description": "Fields of a stored resource type with their classification (`public`, `internal`, `pii`, `financial`, `secret`) and whether you may filter on them. Requires `data:read`. `404` for an unknown type or one outside your scope.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "vertical",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "type",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DataSchema"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/data/connections/{id}/resources/{type}": {
      "get": {
        "operationId": "data.records.list",
        "summary": "List stored records",
        "tags": [
          "data"
        ],
        "description": "One cursor-paginated page of stored records of a type on a connection, masked by field classification (personal data is never revealed here). Supports `filters`, free-text `q`, `sort` and `dir`. Requires `data:read`. `404` when the connection is unknown or outside your tenant scope; `400` `FIELD_NOT_SEARCHABLE` for a filter on a field you may not search; `409` in passthrough mode.",
        "parameters": [
          {
            "schema": {
              "description": "Cursor from the previous page’s `meta.nextCursor`.",
              "example": "eyJ2IjoxfQ",
              "type": "string"
            },
            "in": "query",
            "name": "cursor",
            "description": "Cursor from the previous page’s `meta.nextCursor`."
          },
          {
            "schema": {
              "description": "Page size, 1–200 (default 50).",
              "example": "50",
              "type": "string"
            },
            "in": "query",
            "name": "limit",
            "description": "Page size, 1–200 (default 50)."
          },
          {
            "schema": {
              "description": "Sort key.",
              "example": "updated_at",
              "type": "string",
              "enum": [
                "updated_at",
                "resource_id"
              ]
            },
            "in": "query",
            "name": "sort",
            "description": "Sort key."
          },
          {
            "schema": {
              "description": "Sort direction.",
              "example": "desc",
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            },
            "in": "query",
            "name": "dir",
            "description": "Sort direction."
          },
          {
            "schema": {
              "description": "JSON array of `{ path, op, value }` with `op` one of `eq`, `contains`, `gt`, `lt`, `is_null`. Only searchable fields (see the schema route) are accepted.",
              "example": "[{\"path\":\"title\",\"op\":\"contains\",\"value\":\"CFO\"}]",
              "type": "string"
            },
            "in": "query",
            "name": "filters",
            "description": "JSON array of `{ path, op, value }` with `op` one of `eq`, `contains`, `gt`, `lt`, `is_null`. Only searchable fields (see the schema route) are accepted."
          },
          {
            "schema": {
              "description": "Free-text search over the record id and every searchable field.",
              "example": "acme",
              "type": "string"
            },
            "in": "query",
            "name": "q",
            "description": "Free-text search over the record id and every searchable field."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "type",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DataRecord"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/DataRecordPageMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/data/connections/{id}/resources/{type}/export": {
      "get": {
        "operationId": "data.records.export",
        "summary": "Export stored records as CSV or NDJSON",
        "tags": [
          "data"
        ],
        "description": "Stream every stored record of a type on a connection (up to 100,000) as a `csv` or `ndjson` attachment, masked like the list. `include_pii=true` exports personal data unmasked and additionally requires `data:read_pii`. Requires `data:export`. Every export is written to the audit log as `data.export`.",
        "parameters": [
          {
            "schema": {
              "description": "Sort key.",
              "example": "updated_at",
              "type": "string",
              "enum": [
                "updated_at",
                "resource_id"
              ]
            },
            "in": "query",
            "name": "sort",
            "description": "Sort key."
          },
          {
            "schema": {
              "description": "Sort direction.",
              "example": "desc",
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            },
            "in": "query",
            "name": "dir",
            "description": "Sort direction."
          },
          {
            "schema": {
              "description": "JSON array of `{ path, op, value }` with `op` one of `eq`, `contains`, `gt`, `lt`, `is_null`. Only searchable fields (see the schema route) are accepted.",
              "example": "[{\"path\":\"title\",\"op\":\"contains\",\"value\":\"CFO\"}]",
              "type": "string"
            },
            "in": "query",
            "name": "filters",
            "description": "JSON array of `{ path, op, value }` with `op` one of `eq`, `contains`, `gt`, `lt`, `is_null`. Only searchable fields (see the schema route) are accepted."
          },
          {
            "schema": {
              "description": "Free-text search over the record id and every searchable field.",
              "example": "acme",
              "type": "string"
            },
            "in": "query",
            "name": "q",
            "description": "Free-text search over the record id and every searchable field."
          },
          {
            "schema": {
              "description": "Export format (default `csv`).",
              "example": "csv",
              "type": "string",
              "enum": [
                "csv",
                "ndjson"
              ]
            },
            "in": "query",
            "name": "format",
            "description": "Export format (default `csv`)."
          },
          {
            "schema": {
              "description": "Export personal data unmasked. Requires `data:read_pii`; audited.",
              "example": "false",
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "in": "query",
            "name": "include_pii",
            "description": "Export personal data unmasked. Requires `data:read_pii`; audited."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "type",
            "required": true
          }
        ],
        "responses": {
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/data/connections/{id}/resources/{type}/{rid}": {
      "get": {
        "operationId": "data.records.get",
        "summary": "Read one stored record (masked)",
        "tags": [
          "data"
        ],
        "description": "One stored record with its row metadata, masked by field classification. To see personal data use the `reveal` route. Requires `data:read`. `404` when the connection, type or record is unknown or outside your scope.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "type",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "rid",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DataRecord"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/DataRecordMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/data/connections/{id}/resources/{type}/{rid}/reveal": {
      "post": {
        "operationId": "data.records.reveal",
        "summary": "Reveal the personal data in one stored record",
        "tags": [
          "data"
        ],
        "description": "The stored record with personal data unmasked (secrets are still removed; financial fields follow `data_access.mask_financial`). Requires `data:read` and `data:read_pii`. Every reveal is written to the audit log as `data.pii_reveal`, with the optional `reason`, before the record is returned. The response is `Cache-Control: no-store`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DataRevealBody"
              }
            }
          },
          "description": "Request body to reveal a stored record."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "type",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "rid",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DataRecord"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/DataRecordMeta"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/dashboards": {
      "get": {
        "operationId": "dashboards.list",
        "summary": "List dashboards",
        "tags": [
          "dashboards"
        ],
        "description": "The built-in dashboards, then every dashboard shared with you (your own, those shared with a tenant in your access, those shared with everyone; an admin with access to every tenant sees all), most recently updated first. Requires `dashboards:view`.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Dashboard"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "dashboards.create",
        "summary": "Create a dashboard",
        "tags": [
          "dashboards"
        ],
        "description": "Create a dashboard from up to 24 widgets, each naming a catalog metric, a chart type and a width (1–12 columns). Shared per `audience` (default `private`); `everyone` needs `dashboards:share_all`, and a caller with restricted access may share with and pin only tenants in that access (`403`). Requires `dashboards:edit`. `400` for a metric not in your catalog, a chart that is not one of its metric's `charts` (`Chart <chart> does not fit <metric>`) or an unknown tenant. Writes `dashboard.create` and, when shared or pinned, `dashboard.share` audit entries.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDashboardBody"
              }
            }
          },
          "description": "Request body to create a dashboard."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Dashboard"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/dashboards/metrics": {
      "get": {
        "operationId": "dashboards.metrics.list",
        "summary": "List the metric catalog",
        "tags": [
          "dashboards"
        ],
        "description": "Every metric a widget can chart in your scope: built-in system metrics and per-vertical metrics over stored records. Metrics never read personal-data fields. Requires `dashboards:view`.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MetricInfo"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/dashboards/metrics/{id}": {
      "get": {
        "operationId": "dashboards.metrics.get",
        "summary": "Compute one metric",
        "tags": [
          "dashboards"
        ],
        "description": "One metric over the connections in your tenant scope, for the days `from`..`to` (inclusive, `YYYY-MM-DD`; default the last 30 days, at most 366). Money is never combined across currencies: every money series, total and KPI carries its currency, and `currency` keeps only one. `granularity` sets the buckets of a series over time and `compare=1` adds `previous`, the prior equal-length range. Results are cached for 60 seconds per metric, scope and parameters. Requires `dashboards:view`. `404` for a metric outside your scope, `400` for a bad range or parameter, `409` in passthrough mode. Pass `dashboard` to apply that dashboard's pinned tenants (your scope ∩ its pins), and `connection` and/or `platform` to narrow further to one connection and/or one adapter (system metrics included), kept to `vertical` when given; a connection outside your scope yields no data, and the result echoes the filter as `filter`. `connection` and `platform` also need `connections:read` (`403` otherwise).",
        "parameters": [
          {
            "schema": {
              "description": "First day.",
              "example": "2026-03-01",
              "type": "string"
            },
            "in": "query",
            "name": "from",
            "description": "First day."
          },
          {
            "schema": {
              "description": "Last day.",
              "example": "2026-03-30",
              "type": "string"
            },
            "in": "query",
            "name": "to",
            "description": "Last day."
          },
          {
            "schema": {
              "description": "The dashboard this widget belongs to: applies its pinned tenants (your scope ∩ its pins). 404 when you cannot see it.",
              "example": "dsh_0123456789abcdef0123",
              "type": "string",
              "maxLength": 100
            },
            "in": "query",
            "name": "dashboard",
            "description": "The dashboard this widget belongs to: applies its pinned tenants (your scope ∩ its pins). 404 when you cannot see it."
          },
          {
            "schema": {
              "description": "Keep only this currency (ISO 4217): money metrics keep its amounts, counts with a currency field count only its records, other metrics ignore it.",
              "example": "EUR",
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            },
            "in": "query",
            "name": "currency",
            "description": "Keep only this currency (ISO 4217): money metrics keep its amounts, counts with a currency field count only its records, other metrics ignore it."
          },
          {
            "schema": {
              "$ref": "#/components/schemas/MetricGranularityParam"
            },
            "in": "query",
            "name": "granularity"
          },
          {
            "schema": {
              "description": "`1` adds `previous`: the same metric over the prior equal-length range.",
              "example": "1",
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            },
            "in": "query",
            "name": "compare",
            "description": "`1` adds `previous`: the same metric over the prior equal-length range."
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,100}$",
              "description": "Only this connection. It narrows your scope (and the dashboard’s pins) further; a connection outside them yields no data rather than an error.",
              "example": "0b6f3c1e-8a2d-4c55-9e0f-3d1f2a7b9c10"
            },
            "in": "query",
            "name": "connection"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
              "description": "Only connections of this adapter. Narrows like `connection`; both together mean both.",
              "example": "shopify"
            },
            "in": "query",
            "name": "platform"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[a-z][a-z-]{1,40}$",
              "description": "The dashboard’s vertical. With `connection` or `platform`, keeps the filter to that vertical’s connections (one adapter slug can exist in several verticals, and system metrics read every vertical); alone it filters nothing.",
              "example": "ecommerce"
            },
            "in": "query",
            "name": "vertical"
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MetricResult"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/dashboards/currencies": {
      "get": {
        "operationId": "dashboards.currencies.list",
        "summary": "List currencies to filter by",
        "tags": [
          "dashboards"
        ],
        "description": "The distinct currencies (ISO 4217, sorted) across the money and currency fields the metric catalog reads, over the connections in your tenant scope — the choices for a dashboard's currency filter and a widget's currency pin. Pass `dashboard` to narrow to that dashboard's pinned tenants (your scope ∩ its pins), and `connection` and/or `platform` (kept to `vertical` when given) to list only that connection's or adapter's currencies. Cached for 60 seconds per scope and filter. Requires `dashboards:view`, and `connections:read` too with `connection` or `platform` (`403` otherwise). `400` for a malformed `connection`, `platform` or `vertical`, `404` for a dashboard you cannot see, `409` in passthrough mode.",
        "parameters": [
          {
            "schema": {
              "description": "The dashboard this widget belongs to: applies its pinned tenants (your scope ∩ its pins). 404 when you cannot see it.",
              "example": "dsh_0123456789abcdef0123",
              "type": "string",
              "maxLength": 100
            },
            "in": "query",
            "name": "dashboard",
            "description": "The dashboard this widget belongs to: applies its pinned tenants (your scope ∩ its pins). 404 when you cannot see it."
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,100}$",
              "description": "Only this connection. It narrows your scope (and the dashboard’s pins) further; a connection outside them yields no data rather than an error.",
              "example": "0b6f3c1e-8a2d-4c55-9e0f-3d1f2a7b9c10"
            },
            "in": "query",
            "name": "connection"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
              "description": "Only connections of this adapter. Narrows like `connection`; both together mean both.",
              "example": "shopify"
            },
            "in": "query",
            "name": "platform"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[a-z][a-z-]{1,40}$",
              "description": "The dashboard’s vertical. With `connection` or `platform`, keeps the filter to that vertical’s connections (one adapter slug can exist in several verticals, and system metrics read every vertical); alone it filters nothing.",
              "example": "ecommerce"
            },
            "in": "query",
            "name": "vertical"
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Currency codes, sorted; records without a currency are not listed.",
                      "example": [
                        "EUR",
                        "GBP",
                        "USD"
                      ]
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/dashboards/connections": {
      "get": {
        "operationId": "dashboards.connections.list",
        "summary": "List connections to filter a dashboard by",
        "tags": [
          "dashboards"
        ],
        "description": "The connections in your tenant scope that a dashboard's connection filter can offer, with the adapters among them — narrowed to `vertical`, to a stored dashboard's pinned tenants when `dashboard` is given (your scope ∩ its pins), to one adapter with `platform`, and by `search`, a case-insensitive substring of the connection id or label (an id prefix is enough). `platforms` lists the adapters of the vertical's connections you can see, with counts, ignoring `search` and `platform`. Connections carry only an id, a label, an adapter and a vertical: never a tenant id, a status or a credential, and a connection outside your scope is absent even when searched for by its exact id. `limit` caps the list (default 50, at most 200; other values are clamped); `total` counts every match. Requires `dashboards:view` and `connections:read`. `400` for an unknown vertical or a malformed adapter, `404` for a dashboard you cannot see.",
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/Vertical"
            },
            "in": "query",
            "name": "vertical"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
              "description": "Only connections of this adapter. Narrows like `connection`; both together mean both.",
              "example": "shopify"
            },
            "in": "query",
            "name": "platform"
          },
          {
            "schema": {
              "description": "Case-insensitive substring of the connection id or label; an exact id is listed first.",
              "example": "acme",
              "type": "string",
              "maxLength": 200
            },
            "in": "query",
            "name": "search",
            "description": "Case-insensitive substring of the connection id or label; an exact id is listed first."
          },
          {
            "schema": {
              "description": "The dashboard this widget belongs to: applies its pinned tenants (your scope ∩ its pins). 404 when you cannot see it.",
              "example": "dsh_0123456789abcdef0123",
              "type": "string",
              "maxLength": 100
            },
            "in": "query",
            "name": "dashboard",
            "description": "The dashboard this widget belongs to: applies its pinned tenants (your scope ∩ its pins). 404 when you cannot see it."
          },
          {
            "schema": {
              "description": "How many connections to list: 1–200, default 50.",
              "example": "50",
              "type": "string"
            },
            "in": "query",
            "name": "limit",
            "description": "How many connections to list: 1–200, default 50."
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DashboardConnections"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/dashboards/{id}": {
      "get": {
        "operationId": "dashboards.get",
        "summary": "Read one dashboard",
        "tags": [
          "dashboards"
        ],
        "description": "A built-in dashboard, or one shared with you. Requires `dashboards:view`. `404` for an unknown id or a dashboard not shared with you.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Dashboard"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "dashboards.update",
        "summary": "Edit a dashboard",
        "tags": [
          "dashboards"
        ],
        "description": "Edit your own dashboard (admins may edit any); omitted fields are unchanged. Requires `dashboards:edit`. `409` for a built-in dashboard, `403` for someone else’s or a sharing change you may not make, `400` for an unknown tenant, a metric not in your catalog or a chart that does not fit its metric, `404` when it does not exist or is not visible to you. Writes a `dashboard.update` audit entry, and `dashboard.share` when the audience or pins change.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDashboardBody"
              }
            }
          },
          "description": "Request body to edit a dashboard."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Dashboard"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "dashboards.delete",
        "summary": "Delete a dashboard",
        "tags": [
          "dashboards"
        ],
        "description": "Delete your own dashboard (admins may delete any). Requires `dashboards:edit`. `409` for a built-in, `403` for someone else’s, `404` when it does not exist. Writes a `dashboard.delete` audit entry.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/analytics/superset/status": {
      "get": {
        "operationId": "superset.status",
        "summary": "Embedded Superset status",
        "tags": [
          "superset"
        ],
        "description": "Whether embedded Apache Superset dashboards are configured, and the browser-facing Superset URL the admin UI embeds from. Requires `dashboards:view`.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SupersetStatus"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/analytics/superset/dashboards": {
      "get": {
        "operationId": "superset.dashboards.list",
        "summary": "List embedded Superset dashboards",
        "tags": [
          "superset"
        ],
        "description": "The registered Superset dashboards you may open: those whose extra permission you hold and whose verticals your tenant scope reaches. What each shows is still filtered to your tenants by the guest token. Requires `dashboards:view`. `409 SUPERSET_DISABLED` when Superset is not configured.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SupersetDashboard"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/analytics/superset/dashboards/{id}": {
      "patch": {
        "operationId": "superset.dashboards.update-sharing",
        "summary": "Choose who sees a Superset dashboard",
        "tags": [
          "superset"
        ],
        "description": "Set a registered dashboard’s audience (`tenants` or `everyone`; not `private`) and optional pinned tenants, which narrow its guest-token row-level security to viewer scope ∩ pins. The bootstrap job never changes these. Requires `dashboards:share_all` and access to every tenant (`403 SCOPE_RESTRICTED` for a tenant-restricted caller, since registry entries are deployment-wide). `404` for a dashboard you cannot open, `409 SUPERSET_DISABLED` when Superset is not configured. Writes a `superset.share` audit entry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SupersetSharingBody"
              }
            }
          },
          "description": "Who sees an embedded Superset dashboard."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SupersetDashboard"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/analytics/superset/guest-token": {
      "post": {
        "operationId": "superset.guest-token.create",
        "summary": "Mint a Superset guest token",
        "tags": [
          "superset"
        ],
        "description": "A guest token for one registered dashboard, valid for 5 minutes, carrying a row-level-security clause that limits every query to your tenant scope, narrowed to the dashboard’s pinned tenants when it has any (no clause only when you see every tenant and it is unpinned). Requires `dashboards:view` (and the dashboard’s extra permission, if any). `404` for a dashboard you may not open, `403 SCOPE_EMPTY` when your access is restricted to no tenants, `409 SUPERSET_DISABLED` when Superset is not configured, `502 SUPERSET_UNAVAILABLE` when Superset refuses or cannot be reached. Writes a `superset.guest_token` audit entry at most once per user and dashboard every 10 minutes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SupersetGuestTokenBody"
              }
            }
          },
          "description": "Request body to mint a guest token."
        },
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SupersetGuestToken"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "502": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/destinations/types": {
      "get": {
        "operationId": "destinations.types",
        "summary": "List destination types",
        "tags": [
          "destinations"
        ],
        "description": "Every destination type with its settings form: the non-secret config and write-only secret fields as JSON Schema (types, defaults, descriptions). Types flagged `experimental` work but may still change; a type listed with `available: false` cannot be created. Requires `destinations:manage`.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DestinationTypeInfo"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/destinations": {
      "get": {
        "operationId": "destinations.list",
        "summary": "List destinations",
        "tags": [
          "destinations"
        ],
        "description": "Destinations whose scope lies inside yours, with their last run. Requires `destinations:manage`. `409` `DATA_STORE_DISABLED` in passthrough mode.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Destination"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "destinations.create",
        "summary": "Create a destination",
        "tags": [
          "destinations"
        ],
        "description": "Create a destination. `config` and `secrets` follow the type's schemas (`GET /api/destinations/types`); secrets are stored encrypted and never returned. `scope` must lie inside your own (`403` `SCOPE_EXCEEDS_CALLER`); `includePii` needs `data:read_pii` (`403` `PII_NOT_PERMITTED`) and records you as approver. Every host named must be public unless allow-listed (`400` `HOST_NOT_ALLOWED`). Requires `destinations:manage`; audited as `destination.create`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDestinationBody"
              }
            }
          },
          "description": "Request body to create a destination."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Destination"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/destinations/{id}": {
      "get": {
        "operationId": "destinations.get",
        "summary": "Get a destination",
        "tags": [
          "destinations"
        ],
        "description": "One destination. `404` when unknown or outside your scope. Requires `destinations:manage`.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Destination"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "destinations.update",
        "summary": "Change a destination",
        "tags": [
          "destinations"
        ],
        "description": "Change a destination’s name, config, scope, PII setting, interval or enabled state. Changing the config, scope or PII of a PII destination needs `data:read_pii`; turning it off or disabling it does not. Widening the scope does not re-export skipped rows: run a backfill. Requires `destinations:manage`; audited as `destination.update`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDestinationBody"
              }
            }
          },
          "description": "Request body to change a destination."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Destination"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "destinations.delete",
        "summary": "Delete a destination",
        "tags": [
          "destinations"
        ],
        "description": "Delete a destination with its cursors and run history. Files and rows already exported stay where they are. Requires `destinations:manage`; audited as `destination.delete`.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null",
                  "description": "No content"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/destinations/{id}/credentials": {
      "put": {
        "operationId": "destinations.credentials",
        "summary": "Replace (rotate) destination credentials",
        "tags": [
          "destinations"
        ],
        "description": "Replace every secret of a destination with the ones given (fields left out are cleared). Values are write-only: the response lists only the names set, and the audit row (`destination.credentials_rotate`) records names only. On a PII destination this needs `data:read_pii`. Requires `destinations:manage`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DestinationCredentialsBody"
              }
            }
          },
          "description": "Replace a destination's credentials."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Destination"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/destinations/{id}/test": {
      "post": {
        "operationId": "destinations.test",
        "summary": "Test a destination connection",
        "tags": [
          "destinations"
        ],
        "description": "Build the sink with the stored credentials and prove it can write: a probe object in the bucket, or `CREATE` on the Postgres schema. A failed test still answers `200` with `ok: false` and the reason. Requires `destinations:manage`; audited as `destination.test`.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DestinationTestResult"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/destinations/{id}/run": {
      "post": {
        "operationId": "destinations.run",
        "summary": "Run a destination now",
        "tags": [
          "destinations"
        ],
        "description": "Start an export run now, outside the schedule. `202` with the run id; `409` `RUN_IN_PROGRESS` when one is already running, `409` `DESTINATION_DISABLED` when it is disabled. Requires `destinations:manage`; audited as `destination.run`.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "202": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DestinationRunStarted"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/destinations/{id}/backfill": {
      "post": {
        "operationId": "destinations.backfill",
        "summary": "Backfill a destination",
        "tags": [
          "destinations"
        ],
        "description": "Reset the export cursors — all of them, one vertical’s, or one resource type’s — so the next run re-exports every stored record in scope, then start a run unless `run: false`. Consumers should deduplicate on `_pk`. Requires `destinations:manage`; audited as `destination.backfill`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DestinationBackfillBody"
              }
            }
          },
          "description": "Request body to backfill a destination."
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DestinationBackfillResult"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/destinations/{id}/runs": {
      "get": {
        "operationId": "destinations.runs",
        "summary": "List destination runs",
        "tags": [
          "destinations"
        ],
        "description": "Run history of a destination, newest first: trigger, status, rows and deletions written, files, and the error of a failed run. Requires `destinations:manage`.",
        "parameters": [
          {
            "schema": {
              "description": "How many runs, newest first, 1–500 (default 50).",
              "example": "50",
              "type": "string"
            },
            "in": "query",
            "name": "limit",
            "description": "How many runs, newest first, 1–500 (default 50)."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DestinationRun"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sql-access/status": {
      "get": {
        "operationId": "sqlAccess.status",
        "summary": "Read-only SQL access status",
        "tags": [
          "sql-access"
        ],
        "description": "Backend, provisioning mode, deployed catalog version, advertised read host and warnings. Answers on SQLite too (`backend: sqlite`), where SQL access is unavailable. Requires `sql_access:manage`.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SqlAccessStatus"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sql-access/provision": {
      "post": {
        "operationId": "sqlAccess.provision",
        "summary": "Provision the SQL views",
        "tags": [
          "sql-access"
        ],
        "description": "Create or update the roles, schemas and views now (managed mode only; `409` `MANUAL_MODE` otherwise — use the provisioning script). Deployment-wide, so it needs an all-tenant scope (`403` `SCOPE_TOO_NARROW`). `409` `POSTGRES_REQUIRED` on SQLite. Requires `sql_access:manage`; audited as `sql_access.provision`.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SqlAccessProvisionResult"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sql-access/provision-script": {
      "get": {
        "operationId": "sqlAccess.provisionScript",
        "summary": "Download the provisioning script",
        "tags": [
          "sql-access"
        ],
        "description": "The provisioning SQL as `text/plain` (one `BEGIN … COMMIT` transaction), for manual mode: run it as a role with CREATEROLE. Needs an all-tenant scope. `409` `POSTGRES_REQUIRED` on SQLite. Requires `sql_access:manage`.",
        "responses": {
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sql-access/catalog": {
      "get": {
        "operationId": "sqlAccess.catalog",
        "summary": "List the SQL views and columns",
        "tags": [
          "sql-access"
        ],
        "description": "Every view a SQL login can read, with each column’s type in the masked and unmasked schemas and its classification. Requires `data:read`. `409` `POSTGRES_REQUIRED` on SQLite.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SqlAccessCatalog"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sql-access/principals": {
      "get": {
        "operationId": "sqlAccess.principals.list",
        "summary": "List SQL principals",
        "tags": [
          "sql-access"
        ],
        "description": "SQL logins inside your scope (unmasked ones only for `data:read_pii` holders), including revoked and expired ones. Requires `sql_access:manage`. `409` `POSTGRES_REQUIRED` on SQLite.",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SqlPrincipal"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "sqlAccess.principals.create",
        "summary": "Create a SQL principal",
        "tags": [
          "sql-access"
        ],
        "description": "Create a read-only Postgres login. The response carries its password ONCE (`Cache-Control: no-store`); it is never stored or logged — rotate it if lost. The scope must lie inside yours (`403` `SCOPE_EXCEEDS_CALLER`); `pii: true` needs `data:read_pii` (`403` `PII_NOT_ALLOWED`). `409` `NOT_PROVISIONED` before the views exist, `409` `POSTGRES_REQUIRED` on SQLite. Requires `sql_access:manage`; audited as `sql_access.principal_create` (without the password).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSqlPrincipalBody"
              }
            }
          },
          "description": "Request body to create a SQL principal."
        },
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SqlPrincipalWithPassword"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sql-access/principals/{id}/rotate": {
      "post": {
        "operationId": "sqlAccess.principals.rotate",
        "summary": "Rotate a SQL principal's password",
        "tags": [
          "sql-access"
        ],
        "description": "Generate a new password, returned ONCE (`Cache-Control: no-store`). The old one stops working immediately and open sessions are ended. `404` for a principal unknown or outside your scope. Requires `sql_access:manage`; audited as `sql_access.principal_rotate` (without the password).",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SqlPrincipalWithPassword"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/sql-access/principals/{id}": {
      "delete": {
        "operationId": "sqlAccess.principals.revoke",
        "summary": "Revoke a SQL principal",
        "tags": [
          "sql-access"
        ],
        "description": "Revoke a login: it can no longer sign in, loses its grants and scope, and its open sessions are ended. The record stays, marked `revoked`. Requires `sql_access:manage`; audited as `sql_access.principal_revoke`.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SqlPrincipalRevokeResult"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "servers": [
    {
      "url": "{scheme}://{host}:{port}",
      "description": "OpenSteward admin-api (operator surface)",
      "variables": {
        "scheme": {
          "default": "http",
          "enum": [
            "http",
            "https"
          ],
          "description": "HTTP scheme — http for local dev, https for deployed."
        },
        "host": {
          "default": "localhost",
          "enum": [
            "localhost"
          ],
          "description": "Hostname of the deployment (no port)."
        },
        "port": {
          "default": "3001",
          "enum": [
            "3001"
          ],
          "description": "Port as a string. Use \"443\" for https, \"80\" for http."
        }
      }
    }
  ]
}
