{
  "openapi": "3.0.3",
  "info": {
    "title": "Keryn Cloud API",
    "version": "0.1.0",
    "x-stability": "Pre-1.0: once released, only additive changes inside a minor version. The Usage tag is marked unstable.",
    "description": "Hosted control API at https://api.keryn.app. Scans, results and sharing, usage and credits, keys, workers, pairing and organization security policy. Every organization-scoped call is bound to one organization: send x-keryn-organization to fail fast if the active organization changed. Errors are {\"error\": code}; 429 carries retry-after. Out of scope: /api/auth/* (sign-in, organizations, SSO and SCIM, served by Better Auth) and inbound provider webhooks.",
    "license": {
      "name": "Keryn Software Licence",
      "url": "https://keryn.dev/licensing/"
    }
  },
  "servers": [
    {
      "url": "https://api.keryn.app"
    }
  ],
  "tags": [
    {
      "name": "Service"
    },
    {
      "name": "Sharing"
    },
    {
      "name": "Pairing"
    },
    {
      "name": "Account",
      "description": "Organization and SSO management beyond these calls is served under /api/auth/* by Better Auth and is not part of this contract."
    },
    {
      "name": "Projects"
    },
    {
      "name": "Keys"
    },
    {
      "name": "Usage",
      "description": "Unstable. Credit grants, the starter credit and promo codes landed with this version; the fields of limits, credits and usage events may still change before 1.0."
    },
    {
      "name": "MCP",
      "description": "The hosted Keryn MCP server. Tools and examples: https://keryn.dev/docs/reference/mcp-tools/"
    },
    {
      "name": "AI attribution"
    },
    {
      "name": "Cloud scans"
    },
    {
      "name": "Scans"
    },
    {
      "name": "Billing"
    },
    {
      "name": "Diagnostics"
    },
    {
      "name": "Email"
    },
    {
      "name": "Notifications"
    },
    {
      "name": "Audit and data"
    },
    {
      "name": "Security"
    },
    {
      "name": "Agentic"
    },
    {
      "name": "Builds",
      "description": "Stub. Always refuses until the sandbox runner ships."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Service"
        ],
        "summary": "Liveness.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "service": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "service",
                    "version"
                  ]
                },
                "example": {
                  "status": "ok",
                  "service": "keryn-cloud",
                  "version": "0.1.0"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getEngineHealth",
        "tags": [
          "Service"
        ],
        "summary": "Whether the scan engines loaded. 503 when one did not.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "service": {
                      "type": "string"
                    },
                    "engines": {
                      "type": "object",
                      "properties": {
                        "trust-scanner": {
                          "type": "boolean"
                        },
                        "keryn-mcp": {
                          "type": "boolean"
                        },
                        "keryn-observe-net": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "trust-scanner",
                        "keryn-mcp",
                        "keryn-observe-net"
                      ]
                    }
                  },
                  "required": [
                    "ok",
                    "service",
                    "engines"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "an engine is not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/config": {
      "get": {
        "operationId": "getPublicConfig",
        "tags": [
          "Service"
        ],
        "summary": "Sign-in providers and whether billing is on.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "providers": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "billingEnabled": {
                      "type": "boolean"
                    },
                    "billingMode": {
                      "type": "string"
                    },
                    "methods": {
                      "type": "object",
                      "properties": {
                        "passkey": {
                          "type": "boolean"
                        },
                        "magicLink": {
                          "type": "boolean"
                        },
                        "password": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "passkey",
                        "magicLink",
                        "password"
                      ]
                    },
                    "email": {
                      "type": "object",
                      "properties": {
                        "subscribe": {
                          "type": "boolean"
                        },
                        "preferences": {
                          "type": "boolean"
                        },
                        "publications": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "subscribe",
                        "preferences",
                        "publications"
                      ]
                    },
                    "websiteTests": {
                      "type": "boolean",
                      "description": "Keryn Cloud website tests (kind dast) are switched on: false until their migration is applied."
                    }
                  },
                  "required": [
                    "providers",
                    "billingEnabled",
                    "billingMode",
                    "methods",
                    "email",
                    "websiteTests"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/public/sso-domain": {
      "post": {
        "operationId": "lookupSsoDomain",
        "tags": [
          "Service"
        ],
        "summary": "Whether the domain of an email address has verified single sign-on.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sso": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "sso"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_email",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/s/{token}": {
      "get": {
        "operationId": "openShare",
        "tags": [
          "Sharing"
        ],
        "summary": "Read a shared scan result by link. Public; revoked, expired or switched-off links, and links whose maker left the organization (person, revoked key, or a device whose approver left), answer 404.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{43}$"
            }
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "repo": {
                      "type": "string"
                    },
                    "summary": {
                      "$ref": "#/components/schemas/ResultSummary"
                    },
                    "report": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "repo",
                    "summary",
                    "report",
                    "createdAt"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "share_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/pair/start": {
      "post": {
        "operationId": "startPairing",
        "tags": [
          "Pairing"
        ],
        "summary": "Start pairing a browser, extension, native app or CLI. A signed-in member approves the code.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PairStart"
              },
              "example": {
                "client": "cli",
                "name": "laptop"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PairStarted"
                }
              }
            }
          }
        }
      }
    },
    "/api/pair/token": {
      "post": {
        "operationId": "redeemPairing",
        "tags": [
          "Pairing"
        ],
        "summary": "Poll for the worker token. 202 while pending, 200 once approved (the token is returned a single time), 410 when expired.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pairingCode": {
                    "type": "string",
                    "maxLength": 64
                  }
                },
                "required": [
                  "pairingCode"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PairToken"
                }
              }
            }
          },
          "202": {
            "description": "Still pending.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              }
            }
          },
          "410": {
            "description": "pairing_expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pair": {
      "get": {
        "operationId": "inspectPairing",
        "tags": [
          "Pairing"
        ],
        "summary": "What the approver sees for a user code, before approving.",
        "description": "Browser session only, from the Keryn origin.",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "description": "User code, for example BCDF-2345."
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PairInspect"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "pairing_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pair/approve": {
      "post": {
        "operationId": "approvePairing",
        "tags": [
          "Pairing"
        ],
        "summary": "Approve a pairing as the signed-in member. The device gets scans:create, scans:read, scans:cancel and usage:read, never administration, for 30 days.",
        "description": "Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userCode": {
                    "type": "string"
                  }
                },
                "required": [
                  "userCode"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "approved": {
                      "type": "boolean"
                    },
                    "deviceId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "client": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "approved",
                    "deviceId",
                    "client"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "pairing_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/me": {
      "get": {
        "operationId": "getMe",
        "tags": [
          "Account"
        ],
        "summary": "The calling identity and its active organization.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "actor": {
                      "$ref": "#/components/schemas/Actor"
                    },
                    "organization": {
                      "$ref": "#/components/schemas/Organization",
                      "nullable": true
                    }
                  },
                  "required": [
                    "actor",
                    "organization"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/teams": {
      "get": {
        "operationId": "listTeams",
        "tags": [
          "Account"
        ],
        "summary": "Teams of the organization with their members. Member addresses and names go only to a signed-in member with organization-wide access; other credentials get member ids.",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "teams": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Team"
                      }
                    }
                  },
                  "required": [
                    "teams"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/directory": {
      "get": {
        "operationId": "getDirectory",
        "tags": [
          "Account"
        ],
        "summary": "SCIM endpoint and provisioned directory connections.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "managed": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "credentials": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/DirectoryToken"
                          }
                        }
                      },
                      "required": [
                        "enabled",
                        "credentials"
                      ]
                    },
                    "scimEndpoint": {
                      "type": "string",
                      "format": "uri"
                    },
                    "connections": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ssoProviderId": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "ssoProviderId"
                        ]
                      }
                    }
                  },
                  "required": [
                    "managed",
                    "scimEndpoint",
                    "connections"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/directory/tokens": {
      "post": {
        "operationId": "createDirectoryToken",
        "tags": [
          "Account"
        ],
        "summary": "Create a SCIM directory token (or the first one, which turns self-serve provisioning on). The secret is returned once.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 730,
                    "default": 365
                  }
                },
                "required": []
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Shown once."
                    },
                    "id": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "token",
                    "id",
                    "expiresAt"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_expiry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/directory/tokens/{id}": {
      "delete": {
        "operationId": "revokeDirectoryToken",
        "tags": [
          "Account"
        ],
        "summary": "Revoke a SCIM directory token.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "revoked"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "token_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/projects": {
      "get": {
        "operationId": "listProjects",
        "tags": [
          "Projects"
        ],
        "summary": "Projects the credential can see (100 at most).",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "projects": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Project"
                      }
                    }
                  },
                  "required": [
                    "projects"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createProject",
        "tags": [
          "Projects"
        ],
        "summary": "Create a project.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 100
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Project"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/keys": {
      "get": {
        "operationId": "listApiKeys",
        "tags": [
          "Keys"
        ],
        "summary": "API keys of the organization (100 at most). Secrets are never returned.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "keys": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKey"
                      }
                    }
                  },
                  "required": [
                    "keys"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createApiKey",
        "tags": [
          "Keys"
        ],
        "summary": "Create an organization API key with scopes and an optional project restriction. The key is returned once.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiKeyRequest"
              },
              "example": {
                "name": "ci",
                "scopes": [
                  "scans:create",
                  "scans:read"
                ],
                "expiresInDays": 90
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyCreated"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_key_options | invalid_expiry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "project_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/keys/{id}": {
      "delete": {
        "operationId": "revokeApiKey",
        "tags": [
          "Keys"
        ],
        "summary": "Revoke an API key.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "revoked"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "key_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/workers": {
      "get": {
        "operationId": "listWorkers",
        "tags": [
          "Keys"
        ],
        "summary": "Worker devices of the organization (100 at most).",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Worker"
                      }
                    }
                  },
                  "required": [
                    "workers"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createWorker",
        "tags": [
          "Keys"
        ],
        "summary": "Create a worker device and its token for a client that cannot hold an API key. The token is returned once.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkerRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkerCreated"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_worker_options | invalid_expiry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "project_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/account/earlier": {
      "get": {
        "operationId": "getEarlierAccount",
        "tags": [
          "Account"
        ],
        "summary": "Earlier keryn.app history under the signed-in person's verified email: what can be brought (found) or what was brought (linked). Off unless the service enables it (404). People only.",
        "description": "Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "linked": {
                      "type": "object",
                      "properties": {
                        "organizationId": {
                          "type": "string"
                        },
                        "scans": {
                          "type": "integer"
                        },
                        "domains": {
                          "type": "integer"
                        },
                        "skipped": {
                          "type": "integer"
                        },
                        "linkedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "organizationId",
                        "scans",
                        "domains",
                        "skipped",
                        "linkedAt"
                      ],
                      "nullable": true
                    },
                    "found": {
                      "type": "object",
                      "properties": {
                        "scans": {
                          "type": "integer"
                        },
                        "domains": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "scans",
                        "domains"
                      ],
                      "nullable": true
                    }
                  },
                  "required": [
                    "linked",
                    "found"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "person_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "earlier_account_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "bringEarlierAccount",
        "tags": [
          "Account"
        ],
        "summary": "Copy the earlier keryn.app scans and domains into the active organization, once per person and per earlier account. Domains arrive unverified. Rows that break today's limits are skipped and counted. Needs scan rights in the organization.",
        "description": "Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "organizationId": {
                      "type": "string"
                    },
                    "scans": {
                      "type": "integer"
                    },
                    "domains": {
                      "type": "integer"
                    },
                    "skipped": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "organizationId",
                    "scans",
                    "domains",
                    "skipped"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "person_required | scope_denied | membership_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found | earlier_account_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "earlier_account_already_linked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "earlier_account_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/workers/rotate": {
      "post": {
        "operationId": "rotateWorkerToken",
        "tags": [
          "Pairing"
        ],
        "summary": "Swap the calling device token (x-keryn-worker-token) for a new one. The presented token stops working at once and the new one never outlives the device's approval. Keep only the newest token: presenting a rotated-away token revokes the device as a suspected copy. A paired device works only while the member who approved it belongs to the organization.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Shown once. Send as x-keryn-worker-token."
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "token",
                    "expiresAt"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "worker_token_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/workers/revoke": {
      "post": {
        "operationId": "signOutWorker",
        "tags": [
          "Pairing"
        ],
        "summary": "Sign the calling device out: the device and every token it holds (x-keryn-worker-token) stop working at once. Clients call it when a person signs out, so a copy of the token is useless afterwards. Pair again to sign back in.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "revoked"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "worker_token_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/workers/{id}": {
      "delete": {
        "operationId": "revokeWorker",
        "tags": [
          "Keys"
        ],
        "summary": "Revoke a worker device and every token it holds.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "revoked"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "worker_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/credits": {
      "get": {
        "operationId": "getCredits",
        "tags": [
          "Usage"
        ],
        "summary": "Credit balance with its grants (starter and promo), the restricted part, and whether the starter credit is still available.",
        "description": "Scope: usage:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "usage:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Credits"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/credits/starter": {
      "post": {
        "operationId": "claimStarterCredit",
        "tags": [
          "Usage"
        ],
        "summary": "Claim the one-time starter credit for the organization. Needs a verified email; limited per address and per hour. A repeat call returns the current credits.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Credits"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "starter_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/credits/redeem": {
      "post": {
        "operationId": "redeemPromoCode",
        "tags": [
          "Usage"
        ],
        "summary": "Redeem a promo code for the organization. Every refusal other than rate limiting answers code_invalid, so codes cannot be probed.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "The code, case-insensitive."
                  }
                },
                "required": [
                  "code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Credits"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "code_invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "already_redeemed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "callMcp",
        "tags": [
          "MCP"
        ],
        "summary": "The Keryn MCP server over streamable HTTP, cloud tools only: one JSON-RPC message or a batch per request, answered as JSON (202 with no body for a notification). initialize, ping and tools/list need no credential; tools/call needs an organization API key or a paired device token, and every tool runs as that credential, in its organization, with its scopes.",
        "security": [
          {},
          {
            "apiKey": []
          },
          {
            "workerToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/JsonRpcMessage"
                  },
                  {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/JsonRpcMessage"
                    }
                  }
                ]
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/list"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "additionalProperties": true
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON-RPC parse error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | ambiguous_credentials (tools/call without a valid credential)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "origin_denied (a browser Origin other than Keryn's own or an allowed client)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "body_too_large (64 KiB)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "ingress_rate_limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ai-attribution/policy": {
      "get": {
        "operationId": "getAttributionPolicy",
        "tags": [
          "AI attribution"
        ],
        "summary": "Read the organization's attribution lookback and works-council setting.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttributionPolicy"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setAttributionPolicy",
        "tags": [
          "AI attribution"
        ],
        "summary": "Set the organization's attribution lookback and works-council setting.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "x-keryn-step-up",
            "in": "header",
            "required": false,
            "description": "Fresh step-up proof for this exact policy write.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AttributionPolicy"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttributionPolicy"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_attribution_policy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ai-attribution": {
      "post": {
        "operationId": "analyseAttribution",
        "tags": [
          "AI attribution"
        ],
        "summary": "Attribute AI tool use and AI-assisted commits from commit metadata you post (up to 2,000 commits; never code). The report is returned without storing it. An opted-in webhook may receive only an event and a surface hash. The organization controls lookback and works-council mode. Identity reveals are audited. Per-developer rows need a signed-in organization administrator with a fresh step-up proof. Metered in shadow mode: free when the surface is unchanged.",
        "description": "Scope: scans:create.",
        "parameters": [
          {
            "name": "x-keryn-step-up",
            "in": "header",
            "required": false,
            "description": "Required for aliases and identities. Omit for aggregate attribution.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "x-keryn-stability": "stable",
        "x-keryn-webhook": {
          "$ref": "#/components/schemas/AttributionWebhook"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AttributionRequest"
              },
              "example": {
                "commits": [
                  {
                    "sha": "0123456789abcdef0123456789abcdef01234567",
                    "authoredAt": "2026-11-01T10:00:00Z",
                    "authorName": "Ada",
                    "authorEmail": "ada@example.com",
                    "message": "feat: parser\n\nCo-Authored-By: Claude <noreply@anthropic.com>"
                  }
                ],
                "bucket": "month"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttributionResult"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_commits | invalid_pulls | invalid_files | invalid_developers | invalid_bucket | invalid_json | invalid_encoding | no_commits_in_lookback",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "administrator_required | step_up_required | aggregate_only | cohort_too_small",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "too_many_commits | request_too_large (2 MiB)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "audit_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/domains": {
      "get": {
        "operationId": "listDomains",
        "tags": [
          "Cloud scans"
        ],
        "summary": "Domains of the organization with their verification state.",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domains": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Domain"
                      }
                    }
                  },
                  "required": [
                    "domains"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "addDomain",
        "tags": [
          "Cloud scans"
        ],
        "summary": "Add a domain to verify (20 at most). Returns the existing record when it is already there.",
        "description": "Scope: scans:create.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "A domain name; a leading https:// and any path are dropped."
                  }
                },
                "required": [
                  "domain"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Domain"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "domain_limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "removeDomain",
        "tags": [
          "Cloud scans"
        ],
        "summary": "Remove a domain.",
        "description": "Scope: scans:create.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "The domain to remove."
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "removed"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "domain_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/domains/verify": {
      "post": {
        "operationId": "verifyDomain",
        "tags": [
          "Cloud scans"
        ],
        "summary": "Check the proof of control now. Verification lasts 30 days; each attempt counts against an hourly budget.",
        "description": "Scope: scans:create.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string"
                  }
                },
                "required": [
                  "domain"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Domain"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "domain_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "no_proof (the message names the record to add)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/cloud-scans": {
      "post": {
        "operationId": "createCloudScan",
        "tags": [
          "Cloud scans"
        ],
        "summary": "Run and store a public-address scan inside the request. Website scans (dast) require websiteTests: true from GET /api/public/config.",
        "description": "Scope: scans:create.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CloudScanRequest"
              },
              "example": {
                "kind": "trust",
                "target": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CloudScanRow"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_kind | invalid_target | invalid_domain | invalid_module | module_not_in_cloud | target_refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "domain_not_verified",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "scan_quota (500 stored scans)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate limit | dast_request_limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "scan_failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listCloudScans",
        "tags": [
          "Cloud scans"
        ],
        "summary": "Stored cloud scans, without reports (100 most recent).",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scans": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CloudScanRow"
                      }
                    }
                  },
                  "required": [
                    "scans"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/cloud-scans/{id}": {
      "get": {
        "operationId": "getCloudScan",
        "tags": [
          "Cloud scans"
        ],
        "summary": "One stored cloud scan with its report.",
        "description": "Scope: scans:read.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CloudScan"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "scan_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteCloudScan",
        "tags": [
          "Cloud scans"
        ],
        "summary": "Delete a stored cloud scan.",
        "description": "Scope: scans:create.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "removed"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "scan_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/cloud-scans/usage": {
      "get": {
        "operationId": "getCloudUsage",
        "tags": [
          "Cloud scans"
        ],
        "summary": "This hour's cloud scans and domain checks of the organization against their limits, and when the hour resets. Also what a Cloud scan costs: trust, surface and MCP scans are free; a website test (kind dast) and active probes are charged from the published per-URL table, held before the scan and refused with 402 when the organization cannot pay.",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scans": {
                      "type": "object",
                      "properties": {
                        "used": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "resetsAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "used",
                        "limit",
                        "resetsAt"
                      ]
                    },
                    "domainChecks": {
                      "type": "object",
                      "properties": {
                        "used": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "resetsAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "used",
                        "limit",
                        "resetsAt"
                      ]
                    },
                    "activeScansPerDomainPerDay": {
                      "type": "integer"
                    },
                    "credits": {
                      "type": "object",
                      "properties": {
                        "charged": {
                          "type": "boolean",
                          "description": "False before the service holds and debits credit for Cloud scans: every kind is then free."
                        },
                        "ratesVersion": {
                          "type": "string"
                        },
                        "unit": {
                          "type": "string"
                        },
                        "free": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "dast": {
                          "type": "object",
                          "properties": {
                            "perUrl": {
                              "type": "object",
                              "properties": {
                                "passive": {
                                  "type": "number"
                                },
                                "crawl": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "passive",
                                "crawl"
                              ]
                            },
                            "maxUrls": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "perUrl",
                            "maxUrls"
                          ]
                        },
                        "activeProbes": {
                          "type": "object",
                          "properties": {
                            "perTarget": {
                              "type": "number"
                            },
                            "verifiedDomainOnly": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "perTarget",
                            "verifiedDomainOnly"
                          ]
                        },
                        "rounding": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "charged",
                        "ratesVersion",
                        "unit",
                        "free",
                        "dast",
                        "activeProbes",
                        "rounding"
                      ]
                    }
                  },
                  "required": [
                    "scans",
                    "domainChecks",
                    "activeScansPerDomainPerDay",
                    "credits"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scans": {
      "post": {
        "operationId": "createScan",
        "tags": [
          "Scans"
        ],
        "summary": "Queue a trust scan of a public website. Reserves credits for maxPages; pass Idempotency-Key so a retry cannot reserve twice.",
        "description": "Scope: scans:create.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Unique per intended scan, 1 to 128 visible ASCII characters.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScanRequest"
              },
              "example": {
                "type": "trust-scan",
                "url": "https://example.com",
                "maxPages": 10
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "organizationId": {
                      "type": "string"
                    },
                    "projectId": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true
                    },
                    "input": {
                      "$ref": "#/components/schemas/ScanRequest"
                    },
                    "status": {
                      "type": "string"
                    },
                    "cancelRequested": {
                      "type": "boolean"
                    },
                    "reservedCents": {
                      "type": "integer"
                    },
                    "priceVersion": {
                      "type": "string"
                    },
                    "errorCode": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "id",
                    "organizationId",
                    "projectId",
                    "input",
                    "status",
                    "cancelRequested",
                    "reservedCents",
                    "priceVersion",
                    "errorCode"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_scan | invalid_url | invalid_page_limit | unknown_scan_option",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "allowance_required | payment_hold | insufficient_credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate limit or concurrency",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scan-schedules": {
      "get": {
        "operationId": "listScanSchedules",
        "tags": [
          "Scans"
        ],
        "summary": "Daily and weekly website scans of the organization (at most 20). A member restricted to projects sees those projects' schedules.",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schedules": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "url": {
                            "type": "string"
                          },
                          "maxPages": {
                            "type": "integer"
                          },
                          "projectId": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "cadence": {
                            "type": "string",
                            "enum": [
                              "daily",
                              "weekly"
                            ]
                          },
                          "enabled": {
                            "type": "boolean",
                            "description": "False once the person who created it can no longer run it."
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "nextRunAt": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "lastOccurrenceAt": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "lastJobId": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "lastError": {
                            "type": "string",
                            "description": "Why the last occurrence was not admitted, for example insufficient_allowance.",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "url",
                          "maxPages",
                          "projectId",
                          "cadence",
                          "enabled",
                          "createdBy",
                          "nextRunAt",
                          "lastOccurrenceAt",
                          "lastJobId",
                          "lastError",
                          "createdAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "schedules"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (migration 081 required)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createScanSchedule",
        "tags": [
          "Scans"
        ],
        "summary": "Scan a public website every day or week. The first occurrence is due at once; each is admitted as you, like your own scan (credits reserved, limits applied), and a failed one sends failed_scheduled_scan to those who opted in. Missed occurrences are skipped. The schedule stops when you lose the right to scan.",
        "description": "Scope: scans:create. Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request. Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "maxPages": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50
                  },
                  "projectId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  },
                  "cadence": {
                    "type": "string",
                    "enum": [
                      "daily",
                      "weekly"
                    ]
                  }
                },
                "required": [
                  "url",
                  "cadence"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "url": {
                      "type": "string"
                    },
                    "maxPages": {
                      "type": "integer"
                    },
                    "projectId": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true
                    },
                    "cadence": {
                      "type": "string",
                      "enum": [
                        "daily",
                        "weekly"
                      ]
                    },
                    "enabled": {
                      "type": "boolean",
                      "description": "False once the person who created it can no longer run it."
                    },
                    "createdBy": {
                      "type": "string"
                    },
                    "nextRunAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "lastOccurrenceAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "lastJobId": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true
                    },
                    "lastError": {
                      "type": "string",
                      "description": "Why the last occurrence was not admitted, for example insufficient_allowance.",
                      "nullable": true
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "id",
                    "url",
                    "maxPages",
                    "projectId",
                    "cadence",
                    "enabled",
                    "createdBy",
                    "nextRunAt",
                    "lastOccurrenceAt",
                    "lastJobId",
                    "lastError",
                    "createdAt"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_schedule | invalid_cadence | invalid_url | invalid_page_limit | unknown_scan_option",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "person_required | scope_denied | project_denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "project_not_found | not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "schedule_limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scan-schedules/{id}": {
      "delete": {
        "operationId": "deleteScanSchedule",
        "tags": [
          "Scans"
        ],
        "summary": "Stop and remove a schedule. Scans it already queued are not canceled.",
        "description": "Scope: scans:cancel. Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request. Browser session only, from the Keryn origin.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:cancel",
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "deleted"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "schedule_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scans/{id}": {
      "get": {
        "operationId": "getScan",
        "tags": [
          "Scans"
        ],
        "summary": "Scan status and, once completed, its result.",
        "description": "Scope: scans:read.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Scan"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "job_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scans/{id}/cancel": {
      "post": {
        "operationId": "cancelScan",
        "tags": [
          "Scans"
        ],
        "summary": "Ask a queued or running scan to stop. Unused reservation is released.",
        "description": "Scope: scans:cancel.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:cancel",
        "responses": {
          "202": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cancelRequested": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "cancelRequested"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "job_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/usage/cli": {
      "get": {
        "operationId": "getCliUsage",
        "tags": [
          "Usage"
        ],
        "summary": "Local (CLI and editor) usage of the organization for a period: counts per team, member, device, command or day, or with view=events the recorded runs newest first. Organization administrators only. It holds the command, size class, outcome, duration and time of each run and never a path, repository name or finding. Send Accept: text/csv (or format=csv) for CSV; an export is recorded in the audit trail. Offline licences report nothing.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Start, a date or ISO time. Default: 30 days before to."
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "End, exclusive. Default: the end of today (UTC). At most 366 days."
            }
          },
          {
            "name": "groupBy",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "team",
                "member",
                "device",
                "command",
                "day"
              ],
              "default": "team"
            }
          },
          {
            "name": "view",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "summary",
                "events"
              ],
              "default": "summary"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "The `next` value of the previous page."
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/CliUsageSummary"
                    },
                    {
                      "$ref": "#/components/schemas/CliUsageEvents"
                    }
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_group | invalid_period | invalid_page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "administrator_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (before migration 019)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "reportCliUsage",
        "tags": [
          "Usage"
        ],
        "summary": "Allow-listed CLI usage records (command, size class, outcome, duration, Deep, minute), attributed to the organization, team, account and device and metered in shadow mode. Local scans are 0 credits. Needs migration 019. Migration 057 makes each optional run ID idempotent per organization and device.",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "records": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "v": {
                          "type": "integer"
                        },
                        "command": {
                          "type": "string"
                        },
                        "size": {
                          "type": "string"
                        },
                        "outcome": {
                          "type": "string"
                        },
                        "ms": {
                          "type": "integer"
                        },
                        "deep": {
                          "type": "boolean"
                        },
                        "at": {
                          "type": "integer"
                        },
                        "runId": {
                          "type": "string",
                          "description": "Random version 4 UUID persisted across retries.",
                          "format": "uuid"
                        }
                      },
                      "required": [
                        "v",
                        "command",
                        "size",
                        "outcome",
                        "ms",
                        "deep",
                        "at"
                      ]
                    }
                  }
                },
                "required": [
                  "records"
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accepted": {
                      "type": "integer"
                    },
                    "dropped": {
                      "type": "integer"
                    },
                    "metered": {
                      "type": "integer"
                    },
                    "shadow": {
                      "type": "boolean"
                    },
                    "day": {
                      "type": "string",
                      "description": "UTC day, YYYY-MM-DD."
                    },
                    "scans": {
                      "type": "integer",
                      "description": "The organization's local scans today, every device."
                    },
                    "scansPerDay": {
                      "type": "integer",
                      "description": "The plan's limit, when it has one."
                    },
                    "over": {
                      "type": "boolean",
                      "description": "True when today's limit is reached: clients stop scanning until 00:00 UTC."
                    }
                  },
                  "required": [
                    "accepted",
                    "dropped",
                    "metered",
                    "shadow",
                    "day",
                    "scans",
                    "over"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_usage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "device_required | feature_not_included",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (migration 019 not applied)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "schema_migration_required (run ID supplied before migration 057)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/repo-scans/quote": {
      "get": {
        "operationId": "getRepoScanQuote",
        "tags": [
          "Usage"
        ],
        "summary": "What a hosted analysis of a public repository costs, by size class and stage, before it is run. Hosted repository analysis is not open yet (`available` is false): this is its published price. A repeat of an unchanged repository costs nothing. Local scanning costs no credits.",
        "description": "Scope: usage:read.",
        "parameters": [
          {
            "name": "files",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "description": "Files the analysis would read, after ignores.",
              "minimum": 1
            }
          },
          {
            "name": "stages",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Comma-separated: scout, deep, sca. Default: all three."
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "usage:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ratesVersion": {
                      "type": "string"
                    },
                    "files": {
                      "type": "integer"
                    },
                    "sizeClass": {
                      "type": "string",
                      "enum": [
                        "s",
                        "m",
                        "l",
                        "xl"
                      ]
                    },
                    "stages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "stage": {
                            "type": "string"
                          },
                          "credits": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "stage",
                          "credits"
                        ]
                      }
                    },
                    "ratedCredits": {
                      "type": "number"
                    },
                    "credits": {
                      "type": "integer",
                      "description": "Held before the run and the most a first analysis is charged."
                    },
                    "repeatCredits": {
                      "type": "integer"
                    },
                    "hostedSizeClass": {
                      "type": "boolean"
                    },
                    "available": {
                      "type": "boolean"
                    },
                    "note": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ratesVersion",
                    "files",
                    "sizeClass",
                    "stages",
                    "ratedCredits",
                    "credits",
                    "repeatCredits",
                    "hostedSizeClass",
                    "available",
                    "note"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_files | invalid_stages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "repository_too_large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/usage/statement": {
      "get": {
        "operationId": "getUsageStatement",
        "tags": [
          "Usage"
        ],
        "summary": "What each project, team, member or product consumed in a period, in credits debited from the prepaid balance. The total equals the ledger's usage debits for the period. Send Accept: text/csv (or format=csv) for the same rows as CSV. A member restricted to projects sees those projects only.",
        "description": "Scope: usage:read.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Start of the period, a date or ISO time. Default: the first day of the current UTC month."
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "End of the period, exclusive. Default: one month after from. At most 366 days."
            }
          },
          {
            "name": "groupBy",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "project",
                "team",
                "member",
                "product"
              ],
              "default": "product"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "The `next` value of the previous page."
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "usage:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageStatement"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_group | invalid_period | invalid_page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (before the rated records exist)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "operationId": "listUsage",
        "tags": [
          "Usage"
        ],
        "summary": "Metered usage events (100 most recent), optionally for one project.",
        "description": "Scope: usage:read.",
        "parameters": [
          {
            "name": "projectId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Limit to one project.",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "usage:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/UsageEvent"
                      }
                    },
                    "aiRuns": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "feature": {
                            "type": "string"
                          },
                          "model": {
                            "type": "string"
                          },
                          "occurred_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "amount_cents": {
                            "type": "integer",
                            "description": "Credits debited for the run; 0 when it was not charged."
                          }
                        },
                        "required": [
                          "id",
                          "feature",
                          "model",
                          "occurred_at",
                          "amount_cents"
                        ]
                      }
                    }
                  },
                  "required": [
                    "events",
                    "aiRuns"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/downloads": {
      "get": {
        "operationId": "listDownloads",
        "tags": [
          "Usage"
        ],
        "summary": "The newest CLI release members may download, with its files per platform, their sizes and sha256 digests, and the installer. `release` is null when no release is listed yet. Each `url` is the members-only download route, never a public link.",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "release": {
                      "type": "object",
                      "properties": {
                        "tag": {
                          "type": "string",
                          "description": "The release tag, v<version>."
                        },
                        "version": {
                          "type": "string"
                        },
                        "publishedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "assets": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "cli",
                                  "installer",
                                  "checksums",
                                  "signature",
                                  "other"
                                ]
                              },
                              "platform": {
                                "type": "string",
                                "description": "linux-x64, linux-arm64, darwin-x64, darwin-arm64, win-x64 or win-arm64 for a CLI archive.",
                                "nullable": true
                              },
                              "bytes": {
                                "type": "integer",
                                "nullable": true
                              },
                              "sha256": {
                                "type": "string",
                                "description": "Lower-case hex, when the repository recorded one. The installer verifies SHA256SUMS and its signature regardless.",
                                "nullable": true
                              },
                              "url": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "name",
                              "kind",
                              "platform",
                              "bytes",
                              "sha256",
                              "url"
                            ]
                          }
                        }
                      },
                      "required": [
                        "tag",
                        "version",
                        "publishedAt",
                        "assets"
                      ],
                      "nullable": true
                    }
                  },
                  "required": [
                    "release"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "download_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "download_not_configured | download_repository_not_private",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/downloads/{tag}/{file}": {
      "get": {
        "operationId": "downloadCli",
        "tags": [
          "Usage"
        ],
        "summary": "Download a file of a CLI release (members only: the CLI is never published publicly). Redirects to a short-lived signed URL of that asset of the private release; a browser without a session is redirected to sign in.",
        "description": "Scope: scans:read.",
        "parameters": [
          {
            "name": "tag",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "file",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "302": {
            "description": "Redirect: the Location header holds the target.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "download_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "download_not_configured | download_repository_not_private",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/entitlement": {
      "post": {
        "operationId": "issueEntitlement",
        "tags": [
          "Usage"
        ],
        "summary": "A signed, expiring entitlement token for the calling device (keryn login): organization, team, account, plan, features and limits, with the keys of the requested rule vaults wrapped to the device key. Needs migration 019.",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "deviceKey": {
                    "type": "string",
                    "description": "The device's X25519 public key, base64 of 32 bytes."
                  },
                  "vaults": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "Vault id: the first 32 hex digits of the sha256 of keryn-vault_bg.wasm."
                    }
                  },
                  "machine": {
                    "type": "string",
                    "description": "Optional machine fingerprint (recorded nowhere; reserved for licences)."
                  }
                },
                "required": [
                  "deviceKey"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "KE1.<payload>.<signature>, Ed25519."
                    },
                    "wrapped": {
                      "type": "object",
                      "properties": {
                        "epk": {
                          "type": "string"
                        },
                        "nonce": {
                          "type": "string"
                        },
                        "ct": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "epk",
                        "nonce",
                        "ct"
                      ]
                    },
                    "retired": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A requested vault id whose key is no longer released: that release is retired, update the CLI."
                      }
                    },
                    "plan": {
                      "type": "string"
                    },
                    "features": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "token",
                    "plan",
                    "features",
                    "expiresAt"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_device_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "device_required | feature_not_included | device_limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (migration 019 not applied)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "entitlement_not_configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/oem/admission": {
      "post": {
        "operationId": "admitOemEntitlement",
        "tags": [
          "Usage"
        ],
        "summary": "Admit the entitlement an OEM partner signed for this organization: the Keryn-signed parent naming the partner and its key, and the child the partner signed for this organization. Keryn checks both signatures and bindings, that the parent is registered and not revoked, and reserves the child's allocation against the parent's quotas. The organization's plan is then the child's features and limits until the child ends or the parent is revoked. Needs migrations 075 and 084.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "parent": {
                    "type": "string",
                    "description": "The Keryn-signed parent (typ keryn-oem-parent+jwt)."
                  },
                  "child": {
                    "type": "string",
                    "description": "The partner-signed child for this organization (typ keryn-oem-child+jwt)."
                  }
                },
                "required": [
                  "parent",
                  "child"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The child's jti."
                    },
                    "features": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "limits": {
                      "type": "object",
                      "properties": {},
                      "required": [],
                      "additionalProperties": {
                        "type": "integer"
                      }
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "id",
                    "features",
                    "limits",
                    "expiresAt"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_oem_entitlement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "oem_entitlement_refused | administrator_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (migration 084 not applied)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "entitlement_not_configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/entitlement/keys": {
      "get": {
        "operationId": "getEntitlementKeys",
        "tags": [
          "Service"
        ],
        "summary": "The entitlement and licence verifying keys, public halves only: the current signing key, earlier ones kept for releases that still pin them, and retired (compromised) ones, whose tokens are revoked.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string"
                    },
                    "v": {
                      "type": "integer"
                    },
                    "issuer": {
                      "type": "string"
                    },
                    "keys": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "kid": {
                            "type": "string"
                          },
                          "kinds": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "entitlement",
                                "licence"
                              ]
                            }
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "current",
                              "previous",
                              "retired"
                            ]
                          },
                          "publicKey": {
                            "type": "string",
                            "description": "Ed25519 public key, SPKI PEM"
                          }
                        },
                        "required": [
                          "kid",
                          "kinds",
                          "status",
                          "publicKey"
                        ]
                      }
                    }
                  },
                  "required": [
                    "kind",
                    "v",
                    "issuer",
                    "keys"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/entitlements": {
      "get": {
        "operationId": "listEntitlements",
        "tags": [
          "Usage"
        ],
        "summary": "The organization's entitlements, newest first: device, account, plan, signing key, expiry and revocation.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entitlements": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "jti": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "deviceId": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "deviceName": {
                            "type": "string",
                            "nullable": true
                          },
                          "userId": {
                            "type": "string",
                            "nullable": true
                          },
                          "email": {
                            "type": "string",
                            "nullable": true
                          },
                          "plan": {
                            "type": "string"
                          },
                          "kid": {
                            "type": "string",
                            "nullable": true
                          },
                          "packs": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "issuedAt": {
                            "type": "string"
                          },
                          "expiresAt": {
                            "type": "string"
                          },
                          "revokedAt": {
                            "type": "string",
                            "nullable": true
                          },
                          "revokedReason": {
                            "type": "string",
                            "enum": [
                              "device",
                              "member",
                              "admin",
                              "key"
                            ],
                            "nullable": true
                          },
                          "machine": {
                            "type": "string",
                            "description": "The machine this token was issued to (a 32-hex fingerprint, never the raw machine id). Needs migration 027.",
                            "nullable": true
                          },
                          "boundMachine": {
                            "type": "string",
                            "description": "The machine the device is bound to: the first one it presented.",
                            "nullable": true
                          },
                          "refusedMachine": {
                            "type": "string",
                            "description": "Another machine that presented this device's credentials and was refused.",
                            "nullable": true
                          },
                          "refusedAt": {
                            "type": "string",
                            "description": "When another machine was last refused.",
                            "nullable": true
                          },
                          "refusedCount": {
                            "type": "integer",
                            "description": "How many times another machine was refused."
                          }
                        },
                        "required": [
                          "jti",
                          "deviceId",
                          "deviceName",
                          "userId",
                          "email",
                          "plan",
                          "kid",
                          "packs",
                          "issuedAt",
                          "expiresAt",
                          "revokedAt",
                          "revokedReason"
                        ]
                      }
                    }
                  },
                  "required": [
                    "entitlements"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/entitlements/{id}/revoke": {
      "post": {
        "operationId": "revokeEntitlement",
        "tags": [
          "Usage"
        ],
        "summary": "Revoke an entitlement and the device that holds it; the device signs in again. Online, it stops at its next request; offline, at its token's expiry plus grace.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": {
                      "type": "boolean"
                    },
                    "device": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true
                    }
                  },
                  "required": [
                    "revoked",
                    "device"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "entitlement_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/entitlements/devices/{id}/release": {
      "post": {
        "operationId": "releaseEntitlementMachine",
        "tags": [
          "Usage"
        ],
        "summary": "Release a signed-in device from the machine it is bound to, to move it: its tokens for the old machine are revoked and the next machine that refreshes with the device's credentials becomes its machine. A device is bound to the first machine it presents; any other machine is refused (403 device_machine_mismatch). Needs migration 027.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "released": {
                      "type": "boolean"
                    },
                    "device": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "required": [
                    "released",
                    "device"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "device_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/contract": {
      "get": {
        "operationId": "getContract",
        "tags": [
          "Usage"
        ],
        "summary": "The organization's active contract (enterprise or government), or null.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contract": {
                      "type": "object",
                      "properties": {
                        "plan": {
                          "type": "string",
                          "enum": [
                            "enterprise",
                            "government"
                          ]
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "limits": {
                          "type": "object",
                          "properties": {},
                          "required": [],
                          "additionalProperties": {
                            "type": "integer"
                          }
                        },
                        "offlineAllowed": {
                          "type": "boolean"
                        },
                        "contractRef": {
                          "type": "string"
                        },
                        "startsAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "endsAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "plan",
                        "features",
                        "offlineAllowed",
                        "contractRef",
                        "endsAt"
                      ],
                      "nullable": true
                    }
                  },
                  "required": [
                    "contract"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/licences": {
      "get": {
        "operationId": "listLicences",
        "tags": [
          "Usage"
        ],
        "summary": "Offline licence requests and issued licences for the organization's contract; an issued one carries the file to install with keryn licence install.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contract": {
                      "type": "object",
                      "properties": {
                        "plan": {
                          "type": "string",
                          "enum": [
                            "enterprise",
                            "government"
                          ]
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "limits": {
                          "type": "object",
                          "properties": {},
                          "required": [],
                          "additionalProperties": {
                            "type": "integer"
                          }
                        },
                        "offlineAllowed": {
                          "type": "boolean"
                        },
                        "contractRef": {
                          "type": "string"
                        },
                        "startsAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "endsAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "plan",
                        "features",
                        "offlineAllowed",
                        "contractRef",
                        "endsAt"
                      ],
                      "nullable": true
                    },
                    "licences": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "contractRef": {
                            "type": "string"
                          },
                          "machine": {
                            "type": "string",
                            "description": "sha256 of the machine id"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "issued",
                              "refused",
                              "withdrawn"
                            ]
                          },
                          "refusal": {
                            "type": "string",
                            "nullable": true
                          },
                          "expiresAt": {
                            "type": "string",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "issuedAt": {
                            "type": "string",
                            "nullable": true
                          },
                          "releases": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "description": "A release (rule vault id) this licence opens."
                            }
                          },
                          "licence": {
                            "type": "object",
                            "properties": {
                              "token": {
                                "type": "string",
                                "description": "KL1. licence"
                              },
                              "wrapped": {
                                "type": "object",
                                "properties": {
                                  "epk": {
                                    "type": "string"
                                  },
                                  "nonce": {
                                    "type": "string"
                                  },
                                  "ct": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "epk",
                                  "nonce",
                                  "ct"
                                ]
                              }
                            },
                            "required": [
                              "token"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "contractRef",
                          "machine",
                          "status",
                          "createdAt",
                          "releases"
                        ]
                      }
                    }
                  },
                  "required": [
                    "contract",
                    "licences"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/licences/requests": {
      "post": {
        "operationId": "requestLicence",
        "tags": [
          "Usage"
        ],
        "summary": "File one machine's offline licence request (the JSON keryn licence request writes). Needs a contract that allows offline use; the contract's device limit caps machines.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "request": {
                    "type": "object",
                    "properties": {
                      "kind": {
                        "type": "string",
                        "enum": [
                          "keryn.licence-request"
                        ]
                      },
                      "v": {
                        "type": "integer"
                      },
                      "machine": {
                        "type": "string"
                      },
                      "deviceKey": {
                        "type": "string"
                      },
                      "org": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "kind",
                      "v",
                      "machine",
                      "deviceKey"
                    ]
                  },
                  "label": {
                    "type": "string"
                  }
                },
                "required": [
                  "request"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "contractRef": {
                      "type": "string"
                    },
                    "machine": {
                      "type": "string",
                      "description": "sha256 of the machine id"
                    },
                    "label": {
                      "type": "string",
                      "nullable": true
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "issued",
                        "refused",
                        "withdrawn"
                      ]
                    },
                    "refusal": {
                      "type": "string",
                      "nullable": true
                    },
                    "expiresAt": {
                      "type": "string",
                      "nullable": true
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "issuedAt": {
                      "type": "string",
                      "nullable": true
                    },
                    "releases": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A release (rule vault id) this licence opens."
                      }
                    },
                    "licence": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string",
                          "description": "KL1. licence"
                        },
                        "wrapped": {
                          "type": "object",
                          "properties": {
                            "epk": {
                              "type": "string"
                            },
                            "nonce": {
                              "type": "string"
                            },
                            "ct": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "epk",
                            "nonce",
                            "ct"
                          ]
                        }
                      },
                      "required": [
                        "token"
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "contractRef",
                    "machine",
                    "status",
                    "createdAt",
                    "releases"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_licence_request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "offline_not_in_contract | machine_limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/licences/{id}/withdraw": {
      "post": {
        "operationId": "withdrawLicenceRequest",
        "tags": [
          "Usage"
        ],
        "summary": "Withdraw a pending licence request.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "withdrawn": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "withdrawn"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "licence_request_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/usage/agentic-own-key": {
      "post": {
        "operationId": "reportOwnKeyUsage",
        "tags": [
          "Usage"
        ],
        "summary": "Record one unbilled own-key model run from an account-paired device. Retries of the same run ID are idempotent per account and organization.",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "runId": {
                    "type": "string",
                    "description": "Random version 4 UUID persisted across retries.",
                    "format": "uuid"
                  },
                  "tokensIn": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 1000000000
                  },
                  "tokensOut": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 1000000000
                  }
                },
                "required": [
                  "runId",
                  "tokensIn",
                  "tokensOut"
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accepted": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "accepted"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_usage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "device_required | scope_denied | account_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (migration 040 not applied)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/limits": {
      "get": {
        "operationId": "getLimits",
        "tags": [
          "Usage"
        ],
        "summary": "Credit balance, reservations, concurrency and the current price.",
        "description": "Scope: usage:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "usage:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Limits"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "allowance_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/billing/checkout": {
      "post": {
        "operationId": "createCheckout",
        "tags": [
          "Billing"
        ],
        "summary": "Start a credit purchase with the payment provider. Returns the same session for a repeated Idempotency-Key.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Unique per purchase.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pack": {
                    "type": "string",
                    "description": "Optional pack id from GET /api/v1/billing/plans; omitted means the default pack."
                  }
                },
                "required": [
                  "pack"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "url",
                    "id"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "unknown_pack",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "idempotency_key_reused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "billing_not_configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/billing/settings": {
      "get": {
        "operationId": "getBillingSettings",
        "tags": [
          "Billing"
        ],
        "summary": "The organization's monthly credit cap (null means none), the credits used this calendar month (UTC) and the date the cap resets.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "monthlyCapCredits": {
                      "type": "integer",
                      "nullable": true
                    },
                    "spentThisMonth": {
                      "type": "integer"
                    },
                    "resetsOn": {
                      "type": "string",
                      "format": "date"
                    },
                    "available": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "monthlyCapCredits",
                    "spentThisMonth",
                    "resetsOn",
                    "available"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "setBillingSettings",
        "tags": [
          "Billing"
        ],
        "summary": "Set or clear the monthly credit cap. Hosted work that would pass it (a website scan, a hosted AI run, a Cloud scan) is refused before it starts with 429 spend_cap_reached; owners and administrators are told at 50, 80 and 100 percent of the cap and when the balance runs low. Needs migration 052.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "monthlyCapCredits": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100000000,
                    "nullable": true
                  }
                },
                "required": [
                  "monthlyCapCredits"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "monthlyCapCredits": {
                      "type": "integer",
                      "nullable": true
                    },
                    "spentThisMonth": {
                      "type": "integer"
                    },
                    "resetsOn": {
                      "type": "string",
                      "format": "date"
                    },
                    "available": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "monthlyCapCredits",
                    "spentThisMonth",
                    "resetsOn",
                    "available"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_credit_cap",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "spend_cap_reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/billing/portal": {
      "post": {
        "operationId": "createBillingPortal",
        "tags": [
          "Billing"
        ],
        "summary": "Open the payment provider's customer portal.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  },
                  "required": [
                    "url"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "billing_customer_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "billing_not_configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/billing/plans": {
      "get": {
        "operationId": "getBillingPlans",
        "tags": [
          "Billing"
        ],
        "summary": "What can be bought, with amounts read from the payment provider: top-up packs (credits equal cents) and the monthly Keryn Team plan. `subscription` is the organization's Keryn Team subscription as the payment provider last reported it (null when it never had one; absent before migration 053).",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "packs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "amountCents": {
                            "type": "integer"
                          },
                          "credits": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "id",
                          "amountCents",
                          "credits"
                        ]
                      }
                    },
                    "team": {
                      "type": "object",
                      "properties": {
                        "amountCents": {
                          "type": "integer"
                        },
                        "credits": {
                          "type": "integer"
                        },
                        "interval": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "amountCents",
                        "credits",
                        "interval"
                      ]
                    },
                    "subscription": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "string",
                          "enum": [
                            "active",
                            "canceling",
                            "past_due",
                            "lapsed",
                            "ended"
                          ]
                        },
                        "team": {
                          "type": "boolean",
                          "description": "Whether the organization is on Keryn Team now."
                        },
                        "text": {
                          "type": "string",
                          "description": "The state in words, for the account page."
                        },
                        "date": {
                          "type": "string",
                          "description": "The renewal, end, retry or ended date (YYYY-MM-DD) the text names.",
                          "nullable": true
                        }
                      },
                      "required": [
                        "state",
                        "team",
                        "text",
                        "date"
                      ],
                      "nullable": true
                    }
                  },
                  "required": [
                    "packs",
                    "team"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "billing_not_configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/billing/subscribe": {
      "post": {
        "operationId": "createTeamSubscription",
        "tags": [
          "Billing"
        ],
        "summary": "Start the monthly Keryn Team subscription with the payment provider. Each paid invoice adds the plan's credits once.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Unique per attempt.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "url",
                    "id"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "idempotency_key_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "already_subscribed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "billing_price_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/telemetry": {
      "post": {
        "operationId": "sendTelemetry",
        "tags": [
          "Diagnostics"
        ],
        "summary": "Opt-in product analytics. Each event is rebuilt from an allowlist (enums, counts, durations, a random per-scan run id); anything else is dropped. Nothing about the sender is stored. At most 100 events per call; a global daily ceiling answers 429.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                },
                "required": [
                  "events"
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accepted": {
                      "type": "integer"
                    },
                    "dropped": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "accepted",
                    "dropped"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "intake_full",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/diagnostics": {
      "post": {
        "operationId": "sendDiagnostic",
        "tags": [
          "Diagnostics"
        ],
        "summary": "Send a diagnostic bundle the person previewed (kind keryn.diagnostic). Re-cleaned on arrival, kept 30 days; quote the reference to support. Nothing about the sender is stored.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bundle": {
                    "type": "object",
                    "additionalProperties": true
                  }
                },
                "required": [
                  "bundle"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reference": {
                      "type": "string",
                      "pattern": "^KD-[A-Z0-9]{8}$"
                    },
                    "events": {
                      "type": "integer"
                    },
                    "keptDays": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "reference",
                    "events",
                    "keptDays"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_json | invalid_bundle",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "request too large (256 KiB)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "intake_full",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sharing": {
      "get": {
        "operationId": "getSharing",
        "tags": [
          "Sharing"
        ],
        "summary": "The organization's sharing mode, and what it allows per repository visibility.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "$ref": "#/components/schemas/SharingMode"
                    },
                    "public": {
                      "$ref": "#/components/schemas/SharingByVisibility"
                    },
                    "private": {
                      "$ref": "#/components/schemas/SharingByVisibility"
                    }
                  },
                  "required": [
                    "mode",
                    "public",
                    "private"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "setSharing",
        "tags": [
          "Sharing"
        ],
        "summary": "Set the organization's sharing mode. Switching to off ends every existing link.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mode": {
                    "$ref": "#/components/schemas/SharingMode"
                  }
                },
                "required": [
                  "mode"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "updated"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_mode",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/results": {
      "get": {
        "operationId": "listResults",
        "tags": [
          "Sharing"
        ],
        "summary": "Uploaded scan results (100 most recent).",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ResultRow"
                      }
                    }
                  },
                  "required": [
                    "results"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "uploadResult",
        "tags": [
          "Sharing"
        ],
        "summary": "Upload a result under the sharing mode. Private source, finding text and evidence are never stored; private repositories keep counts only, and only when the mode is public+metadata. The plan bounds the results an organization keeps (409 result_storage_full) and the report bytes it stores in 24 hours (429 result_upload_limit: 100 MiB on Free).",
        "description": "Scope: scans:create.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResultUpload"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "stored": {
                      "type": "string",
                      "enum": [
                        "full",
                        "metadata"
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "stored"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_repo | invalid_visibility | invalid_summary | report_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "sharing_not_permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "result_storage_full (the organization keeps as many results as its plan allows: 10,000 on Free)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "request too large (1 MiB)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/results/{id}": {
      "get": {
        "operationId": "getResult",
        "tags": [
          "Sharing"
        ],
        "summary": "One uploaded result.",
        "description": "Scope: scans:read.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultFull"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "result_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteResult",
        "tags": [
          "Sharing"
        ],
        "summary": "Delete an uploaded result and its links.",
        "description": "Scope: scans:create.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "deleted"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "result_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/results/{id}/share": {
      "post": {
        "operationId": "shareResult",
        "tags": [
          "Sharing"
        ],
        "summary": "Create a share link for a full public-repo result. 1 to 90 days, default 30.",
        "description": "Scope: scans:create.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 90,
                    "default": 30
                  }
                },
                "required": []
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "expiresInDays": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "url",
                    "expiresInDays"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_expiry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "sharing_not_permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "result_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "revokeResultShares",
        "tags": [
          "Sharing"
        ],
        "summary": "Revoke every link of a result.",
        "description": "Scope: scans:create.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "revoked"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "result_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/email/subscribe": {
      "post": {
        "operationId": "subscribeEmail",
        "tags": [
          "Email"
        ],
        "summary": "Ask for publications by email (double opt-in). Answers the same for every address; nothing is sent until the address confirms. Marketing topics are chosen later, in the preference centre.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "publications": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "Offered publications only (GET /api/public/config email.publications); daily, weekly and monthly by default.",
                      "enum": [
                        "daily",
                        "weekly",
                        "monthly",
                        "quarterly",
                        "annual"
                      ]
                    }
                  },
                  "consent": {
                    "type": "string",
                    "description": "The consent wording version the person saw, e.g. 2026-11-17."
                  },
                  "source": {
                    "type": "string",
                    "description": "Where the form is, e.g. keryn.dev/headlines."
                  }
                },
                "required": [
                  "email",
                  "publications",
                  "consent"
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "check_email"
                      ]
                    }
                  },
                  "required": [
                    "ok",
                    "status"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_email | invalid_publications | publication_not_available | consent_required | marketing_needs_preferences",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (mail unavailable or public signup closed)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/email/confirm": {
      "post": {
        "operationId": "confirmEmail",
        "tags": [
          "Email"
        ],
        "summary": "The double opt-in click: activates the requested publications and returns the address's preference token.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "confirmed": {
                      "type": "boolean"
                    },
                    "publications": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "token": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "confirmed",
                    "publications",
                    "token"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_token (wrong, used or expired)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/email/preferences": {
      "post": {
        "operationId": "readEmailPreferences",
        "tags": [
          "Email"
        ],
        "summary": "Read preferences with the token from any Keryn email.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailPreferences"
                }
              }
            }
          },
          "404": {
            "description": "invalid_token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setEmailPreferences",
        "tags": [
          "Email"
        ],
        "summary": "Turn publications and marketing topics on or off. Turning anything on needs the consent wording version; every marketing topic is separate and off by default.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "publications": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    }
                  },
                  "marketing": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    }
                  },
                  "consent": {
                    "type": "string"
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailPreferences"
                }
              }
            }
          },
          "400": {
            "description": "invalid_preferences | consent_required | publication_not_available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "invalid_token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "confirmation_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/email/unsubscribe": {
      "get": {
        "operationId": "openUnsubscribe",
        "tags": [
          "Email"
        ],
        "summary": "An unsubscribe link opened in a browser: the email page, which asks before changing anything (link scanners only GET).",
        "security": [],
        "responses": {
          "200": {
            "description": "Never returned today."
          }
        }
      },
      "post": {
        "operationId": "unsubscribeEmail",
        "tags": [
          "Email"
        ],
        "summary": "RFC 8058 one-click unsubscribe from one list, one marketing topic or everything (list=all). Needs no session; idempotent.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "unsubscribed": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "unsubscribed"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "invalid_token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/email/export": {
      "post": {
        "operationId": "exportEmailData",
        "tags": [
          "Email"
        ],
        "summary": "Everything held about the address: lists, consents with their proof, the consent log and deliveries.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "invalid_token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/email/delete": {
      "post": {
        "operationId": "deleteEmailData",
        "tags": [
          "Email"
        ],
        "summary": "Erase the address and everything about it. A keyed hash is kept so it is not mailed again unless it signs up afresh.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "deleted"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "invalid_token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/email/preferences": {
      "get": {
        "operationId": "accountEmailPreferences",
        "tags": [
          "Email"
        ],
        "summary": "Your own email preferences, for your verified sign-in address, whichever organization is active.",
        "description": "Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailPreferences"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "person_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (migration 023 required)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setAccountEmailPreferences",
        "tags": [
          "Email"
        ],
        "summary": "Change your own email preferences. Your verified address stands in for the confirmation link.",
        "description": "Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "publications": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    }
                  },
                  "marketing": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    }
                  },
                  "consent": {
                    "type": "string"
                  }
                },
                "required": [
                  "publications",
                  "marketing",
                  "consent"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailPreferences"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_preferences | consent_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "person_required | email_unverified",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/email/export": {
      "post": {
        "operationId": "exportAccountEmailData",
        "tags": [
          "Email"
        ],
        "summary": "Download what is held about your own address.",
        "description": "Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "person_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/email/delete": {
      "post": {
        "operationId": "deleteAccountEmailData",
        "tags": [
          "Email"
        ],
        "summary": "Erase what is held about your own address.",
        "description": "Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "deleted"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "person_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/notifications/preferences": {
      "get": {
        "operationId": "notificationPreferences",
        "tags": [
          "Notifications"
        ],
        "summary": "Own opt-in notification preferences. Destinations are operator-owned references, never caller URLs or addresses.",
        "description": "Scope: scans:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "destinations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "enabled",
                    "events",
                    "destinations"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "person_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found (migration 022 required)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setNotificationPreferences",
        "tags": [
          "Notifications"
        ],
        "summary": "Change only your own events and preauthorized Slack/email/webhook destinations. Disabled by default.",
        "description": "Scope: scans:read. Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "assignment",
                        "new_blocking",
                        "expiring_risk",
                        "failed_scheduled_scan",
                        "credit_cap",
                        "credit_low",
                        "attribution_result"
                      ]
                    }
                  },
                  "destinations": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "enabled",
                  "events",
                  "destinations"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "destinations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "enabled",
                    "events",
                    "destinations"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_notification_preferences | notification_destination_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "person_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/notifications/drain": {
      "post": {
        "operationId": "drainNotifications",
        "tags": [
          "Notifications"
        ],
        "summary": "Administrator drains one notification with an explicitly configured transport. Without a transport it returns disabled and sends nothing.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "delivered": {
                      "type": "integer"
                    },
                    "disabled": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "delivered",
                    "disabled"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tracker-claims/{key}": {
      "get": {
        "operationId": "getTrackerClaim",
        "tags": [
          "Sharing"
        ],
        "summary": "Shared tracker export claim for one export key (sha256 of destination, scope and canonical case; none of them is stored). Dark until migration 028 and role provisioning.",
        "description": "Scope: findings:triage.",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "findings:triage",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string"
                    },
                    "phase": {
                      "type": "string",
                      "enum": [
                        "creating",
                        "linked",
                        "uncertain",
                        "retryable"
                      ]
                    },
                    "owner": {
                      "type": "string"
                    },
                    "remote": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "url"
                      ],
                      "nullable": true
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "updatedAt": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "key",
                    "phase",
                    "owner",
                    "remote",
                    "createdAt",
                    "updatedAt"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_claim_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "claim_not_found | not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "acquireTrackerClaim",
        "tags": [
          "Sharing"
        ],
        "summary": "Claim the first create for an export key across the organization's devices. acquired is true only for the client allowed to create; otherwise the current claim (creating elsewhere, uncertain, or linked to its ticket) is returned. A retryable claim may be taken over.",
        "description": "Scope: findings:triage.",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "findings:triage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "owner": {
                    "type": "string",
                    "description": "The claiming client's random id.",
                    "minLength": 8,
                    "maxLength": 100
                  }
                },
                "required": [
                  "owner"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "acquired": {
                      "type": "boolean"
                    },
                    "claim": {
                      "type": "object",
                      "properties": {
                        "key": {
                          "type": "string"
                        },
                        "phase": {
                          "type": "string",
                          "enum": [
                            "creating",
                            "linked",
                            "uncertain",
                            "retryable"
                          ]
                        },
                        "owner": {
                          "type": "string"
                        },
                        "remote": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "id",
                            "url"
                          ],
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "key",
                        "phase",
                        "owner",
                        "remote",
                        "createdAt",
                        "updatedAt"
                      ]
                    }
                  },
                  "required": [
                    "acquired",
                    "claim"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_claim_key | invalid_claim_owner | unknown_claim_option",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateTrackerClaim",
        "tags": [
          "Sharing"
        ],
        "summary": "Record the outcome: the owner reports uncertain or retryable; any triager may link an unlinked claim to the ticket found by its marker. A linked claim keeps its ticket.",
        "description": "Scope: findings:triage.",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "findings:triage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "owner": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 100
                  },
                  "phase": {
                    "type": "string",
                    "enum": [
                      "linked",
                      "uncertain",
                      "retryable"
                    ]
                  },
                  "remote": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "url": {
                        "type": "string",
                        "description": "https URL of the ticket.",
                        "maxLength": 2000
                      }
                    },
                    "required": [
                      "url"
                    ]
                  }
                },
                "required": [
                  "owner",
                  "phase"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string"
                    },
                    "phase": {
                      "type": "string",
                      "enum": [
                        "creating",
                        "linked",
                        "uncertain",
                        "retryable"
                      ]
                    },
                    "owner": {
                      "type": "string"
                    },
                    "remote": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "url"
                      ],
                      "nullable": true
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "updatedAt": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "key",
                    "phase",
                    "owner",
                    "remote",
                    "createdAt",
                    "updatedAt"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_claim_key | invalid_claim_owner | invalid_claim_phase | invalid_claim_remote | unknown_claim_option",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "claim_not_found | not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "claim_owner_mismatch | claim_already_linked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/results/{id}/reviews": {
      "get": {
        "operationId": "listFindingReviews",
        "tags": [
          "Sharing"
        ],
        "summary": "Persistent review history across rescans of the same repository. Dark until migration 020 and role provisioning.",
        "description": "Scope: scans:read.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Fingerprint cursor returned as next.",
              "maxLength": 200
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reviews": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "next": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "reviews",
                    "next"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "result_not_found | not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateFindingReview",
        "tags": [
          "Sharing"
        ],
        "summary": "Administrator records an append-only review and current member assignment. Resolution requires comparable successful paired reports; no release approval is issued.",
        "description": "Scope: scans:create. Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-scope": "scans:create",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fingerprint": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "state": {
                    "type": "string",
                    "enum": [
                      "open",
                      "false_positive",
                      "accepted_risk",
                      "resolved"
                    ]
                  },
                  "owner": {
                    "type": "string",
                    "description": "Current organization member user ID; null clears assignment.",
                    "nullable": true
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 2000
                  },
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "candidateResultId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "fingerprint",
                  "state",
                  "reason",
                  "expectedVersion"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_review | owner_not_member | unknown_review_option",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "administrator_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "result_not_found | finding_not_found | not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "invalid_or_stale_review | comparable_rescan_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/results/{id}/dispositions": {
      "get": {
        "operationId": "listDispositions",
        "tags": [
          "Sharing"
        ],
        "summary": "Triage decisions on the findings of an uploaded result.",
        "description": "Scope: scans:read.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dispositions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Disposition"
                      }
                    }
                  },
                  "required": [
                    "dispositions"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "result_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setDisposition",
        "tags": [
          "Sharing"
        ],
        "summary": "Record a triage decision on one finding (roles owner, admin, member and triage; never viewer). The audit trail keeps who changed it and the state before and after (the note is not copied there).",
        "description": "Scope: findings:triage.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "findings:triage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "findingKey": {
                    "type": "string",
                    "description": "The finding's id in the uploaded report.",
                    "pattern": "^[A-Za-z0-9_.:/@#-]{1,200}$"
                  },
                  "state": {
                    "$ref": "#/components/schemas/DispositionState"
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 1000,
                    "nullable": true
                  }
                },
                "required": [
                  "findingKey",
                  "state"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "findingKey": {
                      "type": "string"
                    },
                    "state": {
                      "$ref": "#/components/schemas/DispositionState"
                    }
                  },
                  "required": [
                    "findingKey",
                    "state"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_finding_key | invalid_state | invalid_note",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "result_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/audit": {
      "get": {
        "operationId": "listAudit",
        "tags": [
          "Audit and data"
        ],
        "summary": "The organization's audit trail, newest first: access, membership, invitations, teams, SSO, MFA, keys, devices, policies, sharing, domains, results, links, dispositions, retention, exports and deletions. Read by a signed-in organization owner or admin, or by an organization API key holding the audit:read scope (not project-restricted; never a worker or device token), so a SIEM can poll it: page with `next` until it is null, newest first, then keep the newest id seen and poll again.",
        "description": "Scope: audit:read.",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "next from the previous page."
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 50
            }
          }
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "audit:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AuditEvent"
                      }
                    },
                    "next": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "events",
                    "next"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_cursor | invalid_limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/audit/export": {
      "post": {
        "operationId": "exportAudit",
        "tags": [
          "Audit and data"
        ],
        "summary": "The whole audit trail as NDJSON, one AuditEvent per line with type audit_event. The export is itself recorded.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/AuditEvent"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/data/retention": {
      "get": {
        "operationId": "getRetention",
        "tags": [
          "Audit and data"
        ],
        "summary": "How long hosted evidence, backups and audit history are kept.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Retention"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "setRetention",
        "tags": [
          "Audit and data"
        ],
        "summary": "Set how many days hosted evidence is kept.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "evidenceDays": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 730
                  }
                },
                "required": [
                  "evidenceDays"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Retention"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_retention",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/data/export": {
      "post": {
        "operationId": "exportData",
        "tags": [
          "Audit and data"
        ],
        "summary": "Everything Keryn Cloud holds for the organization, as NDJSON (one object per line with a type: organization, member, team, project, sharing_policy, retention_policy, domain, api_key, worker_device, scan_result, disposition, share_link, cloud_scan, scan_job, usage_receipt, credit_ledger, deletion_request, audit_event). Streamed, never stored. Credentials appear as identifiers and dates only.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/data/deletions": {
      "get": {
        "operationId": "listDeletions",
        "tags": [
          "Audit and data"
        ],
        "summary": "Deletion requests and their completion.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deletions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DeletionRequest"
                      }
                    }
                  },
                  "required": [
                    "deletions"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "deleteEvidence",
        "tags": [
          "Audit and data"
        ],
        "summary": "Delete all hosted evidence now (uploaded results with their links and dispositions, cloud scans, scan pages and result bodies). Billing receipts, the credit ledger and the audit trail are kept for their own periods. confirm must be the organization id.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "type": "string",
                    "enum": [
                      "evidence"
                    ]
                  },
                  "confirm": {
                    "type": "string",
                    "description": "The active organization's id."
                  }
                },
                "required": [
                  "scope",
                  "confirm"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletionRequest"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_scope | confirmation_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/security/policy": {
      "get": {
        "operationId": "getSecurityPolicy",
        "tags": [
          "Security"
        ],
        "summary": "The organization's MFA, member-scan and SSO enforcement policy.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyRead"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "setSecurityPolicy",
        "tags": [
          "Security"
        ],
        "summary": "Replace the policy. Enforcing SSO needs a verified provider and a session that signed in through it. Turning it on revokes devices people paired before, and invitations are then limited to the provider's verified domains.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PolicyWrite"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": {
                      "type": "boolean"
                    },
                    "revokedDevices": {
                      "type": "integer",
                      "description": "Devices paired by people that were revoked because SSO enforcement was turned on or changed; members pair again through the identity provider."
                    }
                  },
                  "required": [
                    "updated",
                    "revokedDevices"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_policy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "verify_sso_login_before_enforcement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/directory/groups": {
      "get": {
        "operationId": "listDirectoryGroups",
        "tags": [
          "Account"
        ],
        "summary": "SCIM groups your directory pushed to this organization, with their member count and the team linked to each.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "groups": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "displayName": {
                            "type": "string"
                          },
                          "members": {
                            "type": "integer"
                          },
                          "teamId": {
                            "type": "string",
                            "nullable": true
                          }
                        },
                        "required": [
                          "id",
                          "displayName",
                          "members",
                          "teamId"
                        ]
                      }
                    }
                  },
                  "required": [
                    "groups"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/teams/{id}/projects": {
      "put": {
        "operationId": "setTeamProjects",
        "tags": [
          "Account"
        ],
        "summary": "Replace the projects a team gives its members. A member restricted to some projects reaches the union of their own and their teams' projects.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "projectIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                "required": [
                  "projectIds"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "projectIds": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      }
                    }
                  },
                  "required": [
                    "projectIds"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_team_projects",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "team_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/teams/{id}/directory-group": {
      "put": {
        "operationId": "linkTeamToDirectoryGroup",
        "tags": [
          "Account"
        ],
        "summary": "Link a team to one SCIM group of this organization: the team's members become the group's active members now and follow the directory from then on. null removes the link and keeps the members. Keryn never creates a team from a group.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scimGroupId": {
                    "type": "string",
                    "description": "A SCIM group id from listDirectoryGroups",
                    "nullable": true
                  }
                },
                "required": [
                  "scimGroupId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scimGroupId": {
                      "type": "string",
                      "nullable": true
                    },
                    "members": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "scimGroupId",
                    "members"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_directory_link",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "directory_group_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "directory_group_linked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/security/session-policy": {
      "get": {
        "operationId": "getSessionPolicy",
        "tags": [
          "Security"
        ],
        "summary": "The organization's session lifetime and idle timeout. They apply to this organization's requests only.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "maxSessionHours": {
                      "type": "integer",
                      "description": "Hours from sign-in after which this organization refuses the session, 1 to 168; null for the 7-day default",
                      "nullable": true
                    },
                    "idleTimeoutMinutes": {
                      "type": "integer",
                      "description": "Minutes without activity in this organization after which it refuses the session, 5 to 10080; null for none",
                      "nullable": true
                    }
                  },
                  "required": [
                    "maxSessionHours",
                    "idleTimeoutMinutes"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setSessionPolicy",
        "tags": [
          "Security"
        ],
        "summary": "Set the session lifetime and idle timeout for this organization. A refused session gets 401 organization_session_expired or organization_session_idle here and keeps working for the person's other organizations.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "maxSessionHours": {
                    "type": "integer",
                    "description": "Hours from sign-in after which this organization refuses the session, 1 to 168; null for the 7-day default",
                    "nullable": true
                  },
                  "idleTimeoutMinutes": {
                    "type": "integer",
                    "description": "Minutes without activity in this organization after which it refuses the session, 5 to 10080; null for none",
                    "nullable": true
                  }
                },
                "required": [
                  "maxSessionHours",
                  "idleTimeoutMinutes"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "maxSessionHours": {
                      "type": "integer",
                      "description": "Hours from sign-in after which this organization refuses the session, 1 to 168; null for the 7-day default",
                      "nullable": true
                    },
                    "idleTimeoutMinutes": {
                      "type": "integer",
                      "description": "Minutes without activity in this organization after which it refuses the session, 5 to 10080; null for none",
                      "nullable": true
                    }
                  },
                  "required": [
                    "maxSessionHours",
                    "idleTimeoutMinutes"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_session_policy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices": {
      "get": {
        "operationId": "listMyDevices",
        "tags": [
          "Pairing"
        ],
        "summary": "Devices you paired for this organization (browser, extension, desktop app, CLI), with whether each still works.",
        "description": "Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "devices": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "client": {
                            "type": "string"
                          },
                          "expires_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "revoked_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "active": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "client",
                          "expires_at",
                          "revoked_at",
                          "active"
                        ]
                      }
                    }
                  },
                  "required": [
                    "devices"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{id}": {
      "delete": {
        "operationId": "revokeMyDevice",
        "tags": [
          "Pairing"
        ],
        "summary": "End a device you paired. Its tokens and entitlements stop at once; a device someone else paired, or a service account, is not found.",
        "description": "Browser session only, from the Keryn origin.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "revoked"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "device_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/members/{id}/devices": {
      "delete": {
        "operationId": "revokeMemberDevices",
        "tags": [
          "Pairing"
        ],
        "summary": "End every device a member paired for this organization, with their tokens and entitlements. The membership stays. Only an owner can do this to an owner.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": {
                      "type": "integer",
                      "description": "How many devices were ended"
                    }
                  },
                  "required": [
                    "revoked"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "owner_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "member_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sessions": {
      "get": {
        "operationId": "listMySessions",
        "tags": [
          "Security"
        ],
        "summary": "The signed-in person's own sessions (never their tokens).",
        "description": "Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sessions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Session id"
                          },
                          "current": {
                            "type": "boolean",
                            "description": "This request's session"
                          },
                          "createdAt": {
                            "type": "string",
                            "description": "Signed in",
                            "format": "date-time"
                          },
                          "expiresAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "lastSeenAt": {
                            "type": "string",
                            "description": "Last activity in any organization",
                            "format": "date-time",
                            "nullable": true
                          },
                          "ipAddress": {
                            "type": "string",
                            "nullable": true
                          },
                          "userAgent": {
                            "type": "string",
                            "nullable": true
                          }
                        },
                        "required": [
                          "id",
                          "current",
                          "createdAt",
                          "expiresAt",
                          "lastSeenAt",
                          "ipAddress",
                          "userAgent"
                        ]
                      }
                    }
                  },
                  "required": [
                    "sessions"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sessions/{id}": {
      "delete": {
        "operationId": "endMySession",
        "tags": [
          "Security"
        ],
        "summary": "End one of your own sessions, everywhere.",
        "description": "Browser session only, from the Keryn origin.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ended": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "ended"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "session_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/members/{id}/sessions": {
      "delete": {
        "operationId": "endMemberSessions",
        "tags": [
          "Security"
        ],
        "summary": "End a member's sessions for this organization: sessions signed in until now are refused here (401 organization_session_ended); the member's other organizations are unaffected and signing in again works. Only an owner can end an owner's sessions.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifier.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ended": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "ended"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "owner_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "member_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/security/idp-origins": {
      "get": {
        "operationId": "listIdpOrigins",
        "tags": [
          "Security"
        ],
        "summary": "Identity-provider origins this organization trusts for its own SSO connections, and whether it has proved a domain by DNS (needed to add one).",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "origins": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "origin": {
                            "type": "string",
                            "description": "An HTTPS origin, for example https://example.okta.com"
                          },
                          "approvedAt": {
                            "type": "string",
                            "description": "When it was approved",
                            "format": "date-time"
                          },
                          "inUse": {
                            "type": "boolean",
                            "description": "Whether an SSO connection of this organization uses it"
                          }
                        },
                        "required": [
                          "origin",
                          "approvedAt",
                          "inUse"
                        ]
                      }
                    },
                    "domainVerified": {
                      "type": "boolean",
                      "description": "Whether the organization has a domain proved by DNS"
                    }
                  },
                  "required": [
                    "origins",
                    "domainVerified"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "approveIdpOrigin",
        "tags": [
          "Security"
        ],
        "summary": "Trust an identity provider's origin for this organization's SSO connections, so a connection can be added without a change by Keryn. Needs a domain proved by DNS; the origin must be HTTPS on the default port and resolve only to public addresses. No other organization gains any trust.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "description": "The identity provider's HTTPS origin, without a path",
                    "maxLength": 300
                  }
                },
                "required": [
                  "origin"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "origin": {
                      "type": "string",
                      "description": "The origin as stored"
                    },
                    "approvedAt": {
                      "type": "string",
                      "description": "When it was approved",
                      "format": "date-time"
                    },
                    "inUse": {
                      "type": "boolean",
                      "description": "Whether an SSO connection uses it"
                    }
                  },
                  "required": [
                    "origin",
                    "approvedAt",
                    "inUse"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_idp_origin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "domain_verification_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "removeIdpOrigin",
        "tags": [
          "Security"
        ],
        "summary": "Stop trusting an identity provider's origin. Deleting an SSO connection also removes the origin it used.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "parameters": [
          {
            "name": "origin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "The origin to stop trusting."
            }
          }
        ],
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "removed"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_idp_origin",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/security/sso-roles": {
      "get": {
        "operationId": "getSsoRoleMapping",
        "tags": [
          "Security"
        ],
        "summary": "Roles from the identity provider: which groups make a member an admin. null when roles are managed in Keryn only.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused).",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "providerId": {
                      "type": "string",
                      "description": "A verified SSO connection of this organization"
                    },
                    "groupsClaim": {
                      "type": "string",
                      "description": "The OIDC claim or SAML attribute that lists the person's groups",
                      "pattern": "^[A-Za-z0-9_.:/#-]{1,200}$"
                    },
                    "adminGroups": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A group name or id exactly as the identity provider sends it",
                        "maxLength": 200
                      }
                    },
                    "memberGroups": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A group name or id exactly as the identity provider sends it",
                        "maxLength": 200
                      }
                    },
                    "triageGroups": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A group name or id exactly as the identity provider sends it",
                        "maxLength": 200
                      }
                    },
                    "viewerGroups": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A group name or id exactly as the identity provider sends it",
                        "maxLength": 200
                      }
                    }
                  },
                  "required": [
                    "providerId",
                    "groupsClaim",
                    "adminGroups"
                  ],
                  "nullable": true
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setSsoRoleMapping",
        "tags": [
          "Security"
        ],
        "summary": "Set roles from the identity provider. Every SSO sign-in then makes a person an admin when one of their groups is listed and an admin a member when none is (a sign-in without groups counts as none). Owners never change.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "providerId": {
                    "type": "string",
                    "description": "A verified SSO connection of this organization"
                  },
                  "groupsClaim": {
                    "type": "string",
                    "description": "The OIDC claim or SAML attribute that lists the person's groups",
                    "pattern": "^[A-Za-z0-9_.:/#-]{1,200}$"
                  },
                  "adminGroups": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "A group name or id exactly as the identity provider sends it",
                      "maxLength": 200
                    }
                  },
                  "memberGroups": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "A group name or id exactly as the identity provider sends it",
                      "maxLength": 200
                    }
                  },
                  "triageGroups": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "A group name or id exactly as the identity provider sends it",
                      "maxLength": 200
                    }
                  },
                  "viewerGroups": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "A group name or id exactly as the identity provider sends it",
                      "maxLength": 200
                    }
                  }
                },
                "required": [
                  "providerId",
                  "groupsClaim",
                  "adminGroups"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "providerId": {
                      "type": "string",
                      "description": "A verified SSO connection of this organization"
                    },
                    "groupsClaim": {
                      "type": "string",
                      "description": "The OIDC claim or SAML attribute that lists the person's groups",
                      "pattern": "^[A-Za-z0-9_.:/#-]{1,200}$"
                    },
                    "adminGroups": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A group name or id exactly as the identity provider sends it",
                        "maxLength": 200
                      }
                    },
                    "memberGroups": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A group name or id exactly as the identity provider sends it",
                        "maxLength": 200
                      }
                    },
                    "triageGroups": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A group name or id exactly as the identity provider sends it",
                        "maxLength": 200
                      }
                    },
                    "viewerGroups": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A group name or id exactly as the identity provider sends it",
                        "maxLength": 200
                      }
                    }
                  },
                  "required": [
                    "providerId",
                    "groupsClaim",
                    "adminGroups"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_sso_role_mapping",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "sso_provider_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "removeSsoRoleMapping",
        "tags": [
          "Security"
        ],
        "summary": "Stop setting roles from the identity provider; current roles stay.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "removed"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/security/member-access": {
      "post": {
        "operationId": "setMemberAccess",
        "tags": [
          "Security"
        ],
        "summary": "Allow or deny a member to scan, optionally limited to projects.",
        "description": "Needs an organization owner or admin signed in (API keys and worker tokens are refused). Privileged: needs a step-up proof (POST /api/v1/security/step-up) for this exact request.",
        "security": [
          {
            "session": []
          }
        ],
        "x-keryn-admin-only": true,
        "x-keryn-step-up": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberAccess"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "updated"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_member_access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "member_not_found | project_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/security/step-up": {
      "post": {
        "operationId": "proveStepUp",
        "tags": [
          "Security"
        ],
        "summary": "Prove a fresh MFA code for one privileged request, bound to its hash. Signed-in sessions only.",
        "description": "Browser session only, from the Keryn origin.",
        "security": [
          {
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StepUp"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "Proof to send with the privileged request."
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_challenge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "mfa_enrollment_required | invalid_challenge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "challenge_rate_limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agentic/price": {
      "get": {
        "operationId": "getAgenticPrice",
        "tags": [
          "Agentic"
        ],
        "summary": "What each hosted AI feature costs in credits (1 credit is 1 US cent), to show before a run.",
        "description": "Scope: usage:read.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "usage:read",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "available": {
                      "type": "boolean",
                      "description": "False when the service has no model key."
                    },
                    "unit": {
                      "type": "string"
                    },
                    "features": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "task": {
                            "type": "string",
                            "description": "The published task the feature is charged as."
                          },
                          "credits": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "task",
                          "credits"
                        ]
                      }
                    }
                  },
                  "required": [
                    "available",
                    "unit",
                    "features"
                  ]
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agentic": {
      "post": {
        "operationId": "runAgentic",
        "tags": [
          "Agentic"
        ],
        "summary": "Run an AI feature (summary, threat model, scorecard, exceptions, release, or finding investigation) on a redacted scan brief using Keryn's model key. The run's price (GET /api/v1/agentic/price) is held before the model is called and debited when an answer is returned; a refusal, an empty answer or an error is not charged. Finding investigation requires explicit consent and sufficient allowance, then records shadow usage without debiting credits. A daily token cap applies as well.",
        "description": "Scope: scans:create.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgenticRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgenticAnswer"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "unknown_feature | feature_not_priced | invalid_brief | code_not_accepted | consent_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "payment_hold | insufficient_allowance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "scope, role, project, origin or policy refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "quote_changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "brief_too_large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "model_declined",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "agentic_daily_cap",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "agentic_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/builds": {
      "post": {
        "operationId": "createBuild",
        "tags": [
          "Builds"
        ],
        "summary": "Admission check for sandboxed builds. Stub: validates the request and always refuses until the runner ships.",
        "description": "Scope: scans:create.",
        "security": [
          {
            "apiKey": []
          },
          {
            "workerToken": []
          },
          {
            "session": []
          }
        ],
        "x-keryn-scope": "scans:create",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuildRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Never returned today.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "invalid_build",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required | invalid_credential | invalid_worker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "build_not_enabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tenant_rate_limit: the plan's ceiling for this minute is used up; Retry-After says when to try again",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests a minute the organization's plan or contract allows (for a change, the tighter of requests and changes).",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the window resets.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "build_runner_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Organization API key from POST /api/v1/keys. Scopes and project restrictions are fixed at creation."
      },
      "workerToken": {
        "type": "apiKey",
        "in": "header",
        "name": "x-keryn-worker-token",
        "description": "Device token from pairing or POST /api/v1/workers. Do not send together with Authorization."
      },
      "session": {
        "type": "apiKey",
        "in": "cookie",
        "name": "__Secure-better-auth.session_token",
        "description": "Signed-in browser session (HttpOnly, Secure, SameSite=Lax). Mutating calls must come from the Keryn origin."
      }
    },
    "schemas": {
      "EmailPreferences": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "The address these preferences are for: the token holder's or the signed-in person's own."
          },
          "confirmed": {
            "type": "boolean"
          },
          "publications": {
            "type": "object",
            "description": "on, pending (waiting for the confirmation click) or off, per publication.",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "on",
                "pending",
                "off"
              ]
            }
          },
          "marketing": {
            "type": "object",
            "properties": {
              "product_updates": {
                "type": "boolean"
              },
              "offers_promotions": {
                "type": "boolean"
              },
              "partner_offers": {
                "type": "boolean"
              },
              "new_releases": {
                "type": "boolean"
              }
            },
            "required": [
              "product_updates",
              "offers_promotions",
              "partner_offers",
              "new_releases"
            ]
          },
          "unsubscribedFromAll": {
            "type": "boolean"
          },
          "available": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "consentVersion": {
            "type": "string"
          },
          "consentText": {
            "type": "object",
            "properties": {
              "publications": {
                "type": "string"
              },
              "marketing": {
                "type": "string"
              }
            },
            "required": [
              "publications",
              "marketing"
            ]
          }
        },
        "required": [
          "email",
          "confirmed",
          "publications",
          "marketing",
          "unsubscribedFromAll",
          "available",
          "consentVersion"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable machine-readable code, for example invalid_scan."
          },
          "message": {
            "type": "string",
            "description": "Human-readable detail, present when it adds to the code."
          },
          "requestId": {
            "type": "string",
            "description": "Present on internal_error; quote it to support."
          }
        },
        "required": [
          "error"
        ]
      },
      "Scope": {
        "type": "string",
        "description": "What a credential may do.",
        "enum": [
          "scans:create",
          "scans:read",
          "scans:cancel",
          "usage:read",
          "findings:triage",
          "audit:read"
        ]
      },
      "Actor": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "user",
              "api-key",
              "worker"
            ]
          },
          "id": {
            "type": "string"
          },
          "organizationId": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "projectIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "nullable": true
          },
          "role": {
            "type": "string",
            "description": "Organization role of a signed-in user, for example owner or admin."
          },
          "sessionId": {
            "type": "string"
          }
        },
        "required": [
          "kind",
          "id",
          "organizationId",
          "scopes",
          "projectIds"
        ]
      },
      "Organization": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "slug"
        ]
      },
      "Project": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "ScanRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "trust-scan"
            ]
          },
          "url": {
            "type": "string",
            "description": "http or https, default ports only, no credentials in the URL.",
            "format": "uri"
          },
          "maxPages": {
            "type": "integer",
            "description": "1 to 50. Credits are reserved for every page when the scan is queued.",
            "minimum": 1,
            "maximum": 50,
            "default": 10
          },
          "projectId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          }
        },
        "required": [
          "type",
          "url"
        ]
      },
      "Scan": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "organizationId": {
            "type": "string"
          },
          "projectId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "input": {
            "$ref": "#/components/schemas/ScanRequest"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed",
              "canceled"
            ]
          },
          "cancelRequested": {
            "type": "boolean"
          },
          "reservedCents": {
            "type": "integer"
          },
          "priceVersion": {
            "type": "string"
          },
          "errorCode": {
            "type": "string",
            "nullable": true
          },
          "result": {
            "description": "Present on GET only, and only with scans:read. Null until the scan completes.",
            "nullable": true,
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "id",
          "organizationId",
          "projectId",
          "input",
          "status",
          "cancelRequested",
          "reservedCents",
          "priceVersion",
          "errorCode"
        ]
      },
      "Price": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "description": "The rates version a new scan is admitted under."
          },
          "maxPages": {
            "type": "integer"
          },
          "unitCents": {
            "type": "integer",
            "description": "Only before the published table is in force: cents per analysed page, charged on every run."
          },
          "module": {
            "type": "string",
            "description": "The website-testing module a hosted scan is rated as."
          },
          "unit": {
            "type": "string",
            "description": "What is counted: a unique URL."
          },
          "creditsPerUrl": {
            "type": "number",
            "description": "Credits per unique URL checked (1 credit is 1 US cent)."
          },
          "rounding": {
            "type": "string",
            "description": "How a scan's total becomes whole credits, and when a repeat is free."
          }
        },
        "required": [
          "version",
          "maxPages"
        ]
      },
      "Limits": {
        "type": "object",
        "properties": {
          "balance_cents": {
            "type": "integer"
          },
          "reserved_cents": {
            "type": "integer"
          },
          "available_cents": {
            "type": "integer",
            "description": "balance_cents minus reserved_cents."
          },
          "concurrency_limit": {
            "type": "integer"
          },
          "trust_scan_enabled": {
            "type": "boolean"
          },
          "payment_hold": {
            "type": "boolean"
          },
          "debt_cents": {
            "type": "integer"
          },
          "price": {
            "$ref": "#/components/schemas/Price"
          },
          "rate": {
            "type": "object",
            "properties": {
              "plan": {
                "type": "string",
                "description": "The plan or contract the ceilings come from."
              },
              "requestsPerMinute": {
                "type": "integer",
                "description": "Requests a minute to /api/v1 for the organization."
              },
              "mutationsPerMinute": {
                "type": "integer",
                "description": "Of those, requests that change something."
              },
              "cloudScansPerHour": {
                "type": "integer"
              }
            },
            "required": [
              "plan",
              "requestsPerMinute",
              "mutationsPerMinute",
              "cloudScansPerHour"
            ]
          }
        },
        "required": [
          "balance_cents",
          "reserved_cents",
          "available_cents",
          "concurrency_limit",
          "trust_scan_enabled",
          "payment_hold",
          "debt_cents",
          "price",
          "rate"
        ]
      },
      "UsageEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string"
          },
          "job_id": {
            "type": "string",
            "format": "uuid"
          },
          "meter": {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "amount_cents": {
            "type": "integer"
          },
          "price_version": {
            "type": "string"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time"
          },
          "requested_by_kind": {
            "type": "string",
            "description": "Who requested the scan behind this usage: user, api-key or worker",
            "enum": [
              "user",
              "api-key",
              "worker"
            ]
          },
          "requested_by_id": {
            "type": "string",
            "description": "The person's id, the API key's id or the device's id"
          },
          "module": {
            "type": "string",
            "description": "What the work was rated as. Absent before rated records exist.",
            "nullable": true
          },
          "units": {
            "type": "number",
            "description": "Unique URLs in the rated surface.",
            "nullable": true
          },
          "credits": {
            "type": "number",
            "description": "Credits rated after a free repeat or a partial change; amount_cents is this rounded up to a whole credit.",
            "nullable": true
          },
          "list_credits": {
            "type": "number",
            "description": "What a first full charge of the surface would be.",
            "nullable": true
          },
          "deduped": {
            "type": "boolean",
            "description": "True when the surface was unchanged since it was last charged.",
            "nullable": true
          },
          "note": {
            "type": "string",
            "description": "Why the receipt is what it is, when it is not a plain first charge.",
            "nullable": true
          },
          "rates_version": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id",
          "org_id",
          "job_id",
          "meter",
          "quantity",
          "amount_cents",
          "price_version",
          "occurred_at",
          "requested_by_kind",
          "requested_by_id"
        ]
      },
      "CliUsageRow": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "runs": {
            "type": "integer",
            "description": "Every recorded run, refused ones included."
          },
          "scans": {
            "type": "integer",
            "description": "Runs of a scanning command that were not refused: what the plan's daily limit counts."
          },
          "findings": {
            "type": "integer"
          },
          "errors": {
            "type": "integer"
          },
          "refused": {
            "type": "integer"
          },
          "deep": {
            "type": "integer"
          },
          "ms": {
            "type": "integer",
            "description": "Total duration in milliseconds."
          },
          "lastAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "key",
          "name",
          "runs",
          "scans",
          "findings",
          "errors",
          "refused",
          "deep",
          "ms",
          "lastAt"
        ]
      },
      "CliUsageSummary": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          },
          "groupBy": {
            "type": "string",
            "enum": [
              "team",
              "member",
              "device",
              "command",
              "day",
              "organization"
            ]
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CliUsageRow"
            }
          },
          "total": {
            "type": "object",
            "additionalProperties": true
          },
          "next": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "from",
          "to",
          "groupBy",
          "rows",
          "total",
          "next"
        ]
      },
      "CliUsageEvents": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "occurredAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "command": {
                  "type": "string"
                },
                "sizeClass": {
                  "type": "string"
                },
                "outcome": {
                  "type": "string"
                },
                "ms": {
                  "type": "integer"
                },
                "deep": {
                  "type": "boolean"
                },
                "deviceId": {
                  "type": "string",
                  "nullable": true
                },
                "deviceName": {
                  "type": "string",
                  "nullable": true
                },
                "userId": {
                  "type": "string",
                  "nullable": true
                },
                "teamId": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "id",
                "occurredAt",
                "command",
                "sizeClass",
                "outcome",
                "ms",
                "deep",
                "deviceId",
                "deviceName",
                "userId",
                "teamId"
              ]
            }
          },
          "next": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "from",
          "to",
          "events",
          "next"
        ]
      },
      "UsageStatementRow": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "Project, team or member id, or product/module; `unassigned` when the work had none."
          },
          "name": {
            "type": "string"
          },
          "credits": {
            "type": "integer",
            "description": "Credits debited from the prepaid balance."
          },
          "ratedCredits": {
            "type": "number",
            "description": "Credits rated before rounding to whole credits."
          },
          "listCredits": {
            "type": "number",
            "description": "List value with no free repeat."
          },
          "units": {
            "type": "number"
          },
          "events": {
            "type": "integer"
          }
        },
        "required": [
          "key",
          "name",
          "credits",
          "ratedCredits",
          "listCredits",
          "units",
          "events"
        ]
      },
      "UsageStatement": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          },
          "groupBy": {
            "type": "string",
            "enum": [
              "project",
              "team",
              "member",
              "product"
            ]
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageStatementRow"
            }
          },
          "total": {
            "type": "object",
            "properties": {
              "credits": {
                "type": "integer"
              },
              "ratedCredits": {
                "type": "number"
              },
              "listCredits": {
                "type": "number"
              },
              "units": {
                "type": "number"
              },
              "events": {
                "type": "integer"
              }
            },
            "required": [
              "credits",
              "ratedCredits",
              "listCredits",
              "units",
              "events"
            ]
          },
          "next": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "from",
          "to",
          "groupBy",
          "rows",
          "total",
          "next"
        ]
      },
      "ApiKeyRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "expiresInDays": {
            "type": "integer",
            "minimum": 1,
            "maximum": 365,
            "default": 90
          },
          "projectIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "nullable": true
          }
        },
        "required": [
          "name",
          "scopes"
        ]
      },
      "ApiKeyCreated": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "key": {
            "type": "string",
            "description": "Shown once. Store it; Keryn keeps only a hash."
          },
          "name": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "key",
          "name",
          "expiresAt"
        ]
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "start": {
            "type": "string",
            "description": "First characters of the key, for recognition.",
            "nullable": true
          },
          "enabled": {
            "type": "boolean"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastRequest": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "permissions": {
            "type": "object",
            "additionalProperties": true
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "created_by": {
            "type": "string",
            "description": "User id of the administrator who created the key. Keys are organization service accounts and outlive their creator's membership.",
            "nullable": true
          }
        },
        "required": [
          "id",
          "enabled",
          "createdAt"
        ]
      },
      "WorkerRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "expiresInDays": {
            "type": "integer",
            "minimum": 1,
            "maximum": 90,
            "default": 30
          },
          "projectIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "nullable": true
          }
        },
        "required": [
          "name",
          "scopes"
        ]
      },
      "WorkerCreated": {
        "type": "object",
        "properties": {
          "deviceId": {
            "type": "string",
            "format": "uuid"
          },
          "tokenId": {
            "type": "string",
            "format": "uuid"
          },
          "token": {
            "type": "string",
            "description": "Shown once. Send as x-keryn-worker-token."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "deviceId",
          "tokenId",
          "token",
          "expiresAt"
        ]
      },
      "Worker": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "project_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "nullable": true
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "revoked_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "kind": {
            "type": "string",
            "description": "paired: a person approved it from a client and it works only while that person is a member. service: issued by an administrator for automation.",
            "enum": [
              "paired",
              "service"
            ]
          },
          "created_by": {
            "type": "string",
            "description": "User id of the approving member (paired) or issuing administrator (service).",
            "nullable": true
          },
          "active": {
            "type": "boolean",
            "description": "Not revoked, not expired, and (for paired devices) the approver is still a member."
          }
        },
        "required": [
          "id",
          "name",
          "scopes",
          "project_ids",
          "expires_at",
          "revoked_at",
          "kind",
          "created_by",
          "active"
        ]
      },
      "SharingMode": {
        "type": "string",
        "description": "off: nothing is uploaded. public: public-repo results upload in full and can be linked. public+metadata: also private-repo counts, never linkable.",
        "enum": [
          "off",
          "public",
          "public+metadata"
        ]
      },
      "ResultSummary": {
        "type": "object",
        "properties": {
          "findings": {
            "type": "integer"
          },
          "error": {
            "type": "integer"
          },
          "warning": {
            "type": "integer"
          },
          "info": {
            "type": "integer"
          },
          "blocking": {
            "type": "integer"
          },
          "components": {
            "type": "integer"
          },
          "decision": {
            "type": "string",
            "pattern": "^[a-z-]{1,24}$"
          }
        },
        "required": []
      },
      "AttributionRequest": {
        "type": "object",
        "properties": {
          "commits": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sha": {
                  "type": "string",
                  "description": "40 or 64 hex characters"
                },
                "authoredAt": {
                  "type": "string",
                  "description": "ISO 8601",
                  "format": "date-time"
                },
                "authorName": {
                  "type": "string"
                },
                "authorEmail": {
                  "type": "string"
                },
                "committerName": {
                  "type": "string"
                },
                "committerEmail": {
                  "type": "string"
                },
                "message": {
                  "type": "string",
                  "description": "The full message, trailers included. Metadata only: never send diffs or code."
                },
                "note": {
                  "type": "string",
                  "description": "A Git AI authorship note (refs/notes/ai), when the repository has one."
                },
                "authorLogin": {
                  "type": "string"
                },
                "authorType": {
                  "type": "string"
                }
              },
              "required": [
                "sha",
                "authoredAt",
                "authorName",
                "authorEmail",
                "message"
              ]
            }
          },
          "pulls": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "number": {
                  "type": "integer"
                },
                "title": {
                  "type": "string"
                },
                "body": {
                  "type": "string"
                },
                "author": {
                  "type": "string"
                },
                "authorType": {
                  "type": "string"
                },
                "head": {
                  "type": "string",
                  "description": "Source branch"
                },
                "labels": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "mergeSha": {
                  "type": "string"
                },
                "shas": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 500
                }
              },
              "required": [
                "number",
                "title",
                "body",
                "author",
                "head",
                "labels"
              ]
            }
          },
          "files": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A repository path: tool configuration and instruction files are recognised by path."
            }
          },
          "seen": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Commit ids analysed in an earlier request: only the others are new work for metering."
            }
          },
          "bucket": {
            "type": "string",
            "enum": [
              "month",
              "week"
            ]
          },
          "developers": {
            "type": "string",
            "description": "Use off (the default) for the aggregate. Aliases and identities require a signed-in organization administrator with a fresh step-up proof.",
            "enum": [
              "off",
              "aliases",
              "identities"
            ],
            "default": "off"
          },
          "weakSignals": {
            "type": "boolean",
            "description": "Also read the experimental style signals (low confidence, never counted)."
          }
        },
        "required": [
          "commits"
        ]
      },
      "AttributionPolicy": {
        "type": "object",
        "properties": {
          "lookbackDays": {
            "type": "integer",
            "description": "Maximum age of eligible commit metadata. The service does not retain attribution inputs or reports.",
            "minimum": 1,
            "maximum": 730
          },
          "aggregateOnly": {
            "type": "boolean",
            "description": "Works-council mode: totals only, no developer rows, minimum three contributors."
          }
        },
        "required": [
          "lookbackDays",
          "aggregateOnly"
        ]
      },
      "AttributionEvidence": {
        "type": "object",
        "properties": {
          "channel": {
            "type": "string",
            "enum": [
              "trailer",
              "author",
              "message",
              "note",
              "pr",
              "file",
              "style"
            ]
          },
          "rule": {
            "type": "string"
          },
          "where": {
            "type": "string"
          },
          "quote": {
            "type": "string"
          }
        },
        "required": [
          "channel",
          "rule",
          "where"
        ]
      },
      "AttributionReport": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string",
            "enum": [
              "keryn.ai-attribution/1"
            ]
          },
          "engine": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "enum": [
                  "keryn-ai-attribution"
                ]
              },
              "version": {
                "type": "string"
              },
              "ruleset": {
                "type": "string"
              },
              "rules": {
                "type": "integer"
              }
            },
            "required": [
              "name",
              "version",
              "ruleset",
              "rules"
            ]
          },
          "range": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string"
              },
              "to": {
                "type": "string"
              },
              "commits": {
                "type": "integer"
              },
              "truncated": {
                "type": "boolean"
              }
            },
            "required": [
              "commits"
            ]
          },
          "repo": {
            "type": "object",
            "properties": {
              "commits": {
                "type": "integer"
              },
              "declared": {
                "type": "integer"
              },
              "authored": {
                "type": "integer"
              },
              "assisted": {
                "type": "integer"
              },
              "weak": {
                "type": "integer"
              },
              "automation": {
                "type": "integer"
              },
              "declaredShare": {
                "type": "number",
                "description": "Lower bound on declared involvement among non-automation commits."
              },
              "byTool": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "tool": {
                      "type": "string"
                    },
                    "commits": {
                      "type": "integer"
                    },
                    "authored": {
                      "type": "integer"
                    },
                    "assisted": {
                      "type": "integer"
                    },
                    "confidence": {
                      "type": "object",
                      "properties": {
                        "high": {
                          "type": "integer"
                        },
                        "medium": {
                          "type": "integer"
                        },
                        "low": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "high",
                        "medium",
                        "low"
                      ]
                    },
                    "firstSeen": {
                      "type": "string"
                    },
                    "lastSeen": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "tool",
                    "commits",
                    "authored",
                    "assisted",
                    "confidence"
                  ]
                }
              },
              "series": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "period": {
                      "type": "string"
                    },
                    "commits": {
                      "type": "integer"
                    },
                    "declared": {
                      "type": "integer"
                    },
                    "authored": {
                      "type": "integer"
                    },
                    "assisted": {
                      "type": "integer"
                    },
                    "weak": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "period",
                    "commits",
                    "declared",
                    "authored",
                    "assisted",
                    "weak"
                  ]
                }
              }
            },
            "required": [
              "commits",
              "declared",
              "authored",
              "assisted",
              "weak",
              "automation",
              "byTool",
              "series"
            ]
          },
          "configured": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tool": {
                  "type": "string"
                },
                "confidence": {
                  "type": "string",
                  "enum": [
                    "high",
                    "medium",
                    "low"
                  ]
                },
                "files": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "role": {
                        "type": "string"
                      },
                      "rule": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "role",
                      "rule"
                    ]
                  }
                }
              },
              "required": [
                "tool",
                "confidence",
                "files"
              ]
            }
          },
          "developers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "commits": {
                  "type": "integer"
                },
                "declared": {
                  "type": "integer"
                },
                "authored": {
                  "type": "integer"
                },
                "assisted": {
                  "type": "integer"
                },
                "weak": {
                  "type": "integer"
                },
                "automation": {
                  "type": "integer"
                },
                "declaredShare": {
                  "type": "number",
                  "description": "Lower bound on declared involvement among non-automation commits."
                },
                "byTool": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "tool": {
                        "type": "string"
                      },
                      "commits": {
                        "type": "integer"
                      },
                      "authored": {
                        "type": "integer"
                      },
                      "assisted": {
                        "type": "integer"
                      },
                      "confidence": {
                        "type": "object",
                        "properties": {
                          "high": {
                            "type": "integer"
                          },
                          "medium": {
                            "type": "integer"
                          },
                          "low": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "high",
                          "medium",
                          "low"
                        ]
                      },
                      "firstSeen": {
                        "type": "string"
                      },
                      "lastSeen": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "tool",
                      "commits",
                      "authored",
                      "assisted",
                      "confidence"
                    ]
                  }
                },
                "series": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "period": {
                        "type": "string"
                      },
                      "commits": {
                        "type": "integer"
                      },
                      "declared": {
                        "type": "integer"
                      },
                      "authored": {
                        "type": "integer"
                      },
                      "assisted": {
                        "type": "integer"
                      },
                      "weak": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "period",
                      "commits",
                      "declared",
                      "authored",
                      "assisted",
                      "weak"
                    ]
                  }
                },
                "developer": {
                  "type": "string"
                },
                "identity": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "name",
                    "email"
                  ]
                }
              },
              "required": [
                "commits",
                "declared",
                "authored",
                "assisted",
                "weak",
                "automation",
                "byTool",
                "series",
                "developer"
              ]
            }
          },
          "surfaceHash": {
            "type": "string"
          },
          "coverage": {
            "type": "object",
            "properties": {
              "channels": {
                "type": "object",
                "properties": {
                  "trailer": {
                    "type": "string",
                    "enum": [
                      "read",
                      "not-available",
                      "off"
                    ]
                  },
                  "author": {
                    "type": "string",
                    "enum": [
                      "read",
                      "not-available",
                      "off"
                    ]
                  },
                  "message": {
                    "type": "string",
                    "enum": [
                      "read",
                      "not-available",
                      "off"
                    ]
                  },
                  "note": {
                    "type": "string",
                    "enum": [
                      "read",
                      "not-available",
                      "off"
                    ]
                  },
                  "pr": {
                    "type": "string",
                    "enum": [
                      "read",
                      "not-available",
                      "off"
                    ]
                  },
                  "file": {
                    "type": "string",
                    "enum": [
                      "read",
                      "not-available",
                      "off"
                    ]
                  },
                  "style": {
                    "type": "string",
                    "enum": [
                      "read",
                      "not-available",
                      "off"
                    ]
                  }
                },
                "required": [
                  "trailer",
                  "author",
                  "message",
                  "note",
                  "pr",
                  "file",
                  "style"
                ]
              },
              "limits": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "channels",
              "limits"
            ]
          },
          "samples": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sha": {
                  "type": "string"
                },
                "at": {
                  "type": "string"
                },
                "tool": {
                  "type": "string"
                },
                "involvement": {
                  "type": "string",
                  "enum": [
                    "authored",
                    "assisted",
                    "configured",
                    "signal"
                  ]
                },
                "confidence": {
                  "type": "string",
                  "enum": [
                    "high",
                    "medium",
                    "low"
                  ]
                },
                "evidence": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AttributionEvidence"
                  }
                }
              },
              "required": [
                "sha",
                "at",
                "tool",
                "involvement",
                "confidence",
                "evidence"
              ]
            }
          }
        },
        "required": [
          "schema",
          "engine",
          "range",
          "repo",
          "configured",
          "surfaceHash",
          "coverage",
          "samples"
        ]
      },
      "AttributionWebhook": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string",
            "enum": [
              "keryn.dev/notification/v1"
            ]
          },
          "event": {
            "type": "string",
            "enum": [
              "attribution_result"
            ]
          },
          "idempotencyKey": {
            "type": "string"
          },
          "surfaceHash": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "sourceIncluded": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "schema",
          "event",
          "idempotencyKey",
          "surfaceHash",
          "title",
          "text",
          "url",
          "sourceIncluded"
        ]
      },
      "AttributionResult": {
        "type": "object",
        "properties": {
          "report": {
            "$ref": "#/components/schemas/AttributionReport"
          },
          "metering": {
            "type": "object",
            "properties": {
              "product": {
                "type": "string"
              },
              "module": {
                "type": "string"
              },
              "shadow": {
                "type": "boolean"
              },
              "credits": {
                "type": "number"
              },
              "listCredits": {
                "type": "number"
              },
              "deduped": {
                "type": "boolean"
              },
              "ratesVersion": {
                "type": "string"
              },
              "surfaceHash": {
                "type": "string"
              },
              "metered": {
                "type": "boolean",
                "description": "false when this deployment has no meter wired"
              }
            },
            "required": [
              "product",
              "module",
              "shadow",
              "credits",
              "listCredits",
              "deduped",
              "ratesVersion",
              "surfaceHash"
            ]
          }
        },
        "required": [
          "report",
          "metering"
        ]
      },
      "ResultUpload": {
        "type": "object",
        "properties": {
          "repo": {
            "type": "string",
            "description": "owner/name",
            "pattern": "^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$"
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "summary": {
            "$ref": "#/components/schemas/ResultSummary"
          },
          "report": {
            "type": "object",
            "additionalProperties": true,
            "description": "The Keryn result JSON. Required when the stored detail is full (public repositories)."
          }
        },
        "required": [
          "repo",
          "visibility",
          "summary"
        ]
      },
      "SharingByVisibility": {
        "type": "string",
        "description": "What an upload of a repository with this visibility may contain under the mode.",
        "enum": [
          "full",
          "metadata",
          "off"
        ]
      },
      "AuditEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Opaque, stable. e: database-recorded change, a: action recorded by the API."
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "actor": {
            "type": "string",
            "description": "User id, or kind:id for an API key or device, or system:retention, system:restore, directory. Null when the change came from an operator or the scheduler.",
            "nullable": true
          },
          "action": {
            "type": "string",
            "description": "table.insert|update|delete for recorded changes (member.update, apikey.delete, result_dispositions.update, ...), or an API action (audit.exported, data.exported, key.revoked, ...)."
          },
          "target": {
            "type": "string",
            "description": "Identifier of the changed object."
          },
          "targetType": {
            "type": "string",
            "nullable": true
          },
          "before": {
            "type": "object",
            "additionalProperties": true,
            "description": "Allowlisted fields before the change. Never secrets, tokens, key material, IdP configuration or free-text notes.",
            "nullable": true
          },
          "after": {
            "type": "object",
            "additionalProperties": true,
            "description": "Allowlisted fields after the change.",
            "nullable": true
          }
        },
        "required": [
          "id",
          "at",
          "actor",
          "action",
          "target",
          "targetType",
          "before",
          "after"
        ]
      },
      "Disposition": {
        "type": "object",
        "properties": {
          "findingKey": {
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/DispositionState"
          },
          "note": {
            "type": "string",
            "nullable": true
          },
          "decidedBy": {
            "type": "string"
          },
          "decidedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "findingKey",
          "state",
          "note",
          "decidedBy",
          "decidedAt"
        ]
      },
      "DispositionState": {
        "type": "string",
        "description": "A triage decision on one finding of an uploaded result.",
        "enum": [
          "open",
          "accepted",
          "false_positive",
          "fixed"
        ]
      },
      "Retention": {
        "type": "object",
        "properties": {
          "evidenceDays": {
            "type": "integer",
            "description": "Uploaded results, cloud scans and scan pages and result bodies older than this are deleted. 1 to 730, default 365."
          },
          "backupDays": {
            "type": "integer",
            "description": "Longest a backup is kept: deleted data is gone from every backup this many days after deletion."
          },
          "auditDays": {
            "type": "integer",
            "description": "Audit history is kept this long (13 months)."
          }
        },
        "required": [
          "evidenceDays",
          "backupDays",
          "auditDays"
        ]
      },
      "DeletionRequest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "scope": {
            "type": "string",
            "enum": [
              "evidence"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ]
          },
          "requestedBy": {
            "type": "string"
          },
          "counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "goneFromBackupsBy": {
            "type": "string",
            "description": "After this time no backup holds the deleted rows. Until then a restore replays the deletion (tombstones).",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "scope",
          "status",
          "requestedBy",
          "createdAt"
        ]
      },
      "ResultRow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "repo": {
            "type": "string"
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "detail": {
            "type": "string",
            "enum": [
              "full",
              "metadata"
            ]
          },
          "summary": {
            "$ref": "#/components/schemas/ResultSummary"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "repo",
          "visibility",
          "detail",
          "summary",
          "created_at"
        ]
      },
      "ResultFull": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ResultRow"
          },
          {
            "type": "object",
            "properties": {
              "report": {
                "type": "object",
                "nullable": true,
                "additionalProperties": true
              },
              "org_id": {
                "type": "string"
              },
              "created_by": {
                "type": "string"
              }
            }
          }
        ]
      },
      "PolicyRead": {
        "type": "object",
        "properties": {
          "require_mfa": {
            "type": "boolean"
          },
          "member_can_scan": {
            "type": "boolean"
          },
          "sso_provider_id": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [],
        "additionalProperties": true
      },
      "PolicyWrite": {
        "type": "object",
        "properties": {
          "requireMfa": {
            "type": "boolean"
          },
          "memberCanScan": {
            "type": "boolean"
          },
          "ssoProviderId": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "requireMfa",
          "memberCanScan",
          "ssoProviderId"
        ]
      },
      "MemberAccess": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string",
            "maxLength": 128
          },
          "canScan": {
            "type": "boolean"
          },
          "projectIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "nullable": true
          }
        },
        "required": [
          "userId",
          "canScan"
        ]
      },
      "Team": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "members": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string"
                },
                "email": {
                  "type": "string",
                  "description": "Only for a signed-in member with organization-wide access; absent for API keys, paired devices and project-restricted members (#2777)."
                },
                "name": {
                  "type": "string",
                  "description": "Present with email."
                }
              },
              "required": [
                "userId"
              ]
            }
          },
          "projectIds": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A project the team gives its members (#361); the list is absent before the service schema has team access",
              "format": "uuid"
            }
          },
          "scimGroupId": {
            "type": "string",
            "description": "The SCIM group the team's members follow, or null",
            "nullable": true
          }
        },
        "required": [
          "id",
          "name",
          "members"
        ]
      },
      "AgenticRequest": {
        "type": "object",
        "properties": {
          "feature": {
            "type": "string",
            "enum": [
              "summary",
              "threat-model",
              "scorecard",
              "exceptions",
              "release",
              "finding-investigation"
            ]
          },
          "brief": {
            "type": "object",
            "description": "The bounded, redacted scan brief the web app builds. At most 60 findings, 80,000 characters; no source code. finding-investigation accepts only finding.rule and finding.severity metadata.",
            "additionalProperties": true
          },
          "extra": {
            "type": "object",
            "additionalProperties": true,
            "description": "Feature input, at most 60,000 characters. finding-investigation requires confirmed: true and quotedCredits from the price endpoint."
          }
        },
        "required": [
          "feature",
          "brief"
        ]
      },
      "AgenticAnswer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "text": {
            "type": "string",
            "description": "One JSON document as text, matching the feature schema."
          },
          "model": {
            "type": "string"
          },
          "usage": {
            "type": "object",
            "properties": {
              "input": {
                "type": "integer"
              },
              "output": {
                "type": "integer"
              },
              "cacheRead": {
                "type": "integer"
              },
              "cacheWrite": {
                "type": "integer"
              }
            },
            "required": [
              "input",
              "output",
              "cacheRead",
              "cacheWrite"
            ]
          },
          "credits": {
            "type": "integer",
            "description": "Credits debited for this run; 0 when it was not charged."
          }
        },
        "required": [
          "id",
          "text",
          "model",
          "usage",
          "credits"
        ]
      },
      "BuildRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "build"
            ]
          },
          "repo": {
            "type": "string",
            "description": "owner/name"
          },
          "ref": {
            "type": "string",
            "default": "HEAD"
          },
          "dockerfile": {
            "type": "string",
            "default": "Dockerfile"
          },
          "maxMinutes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30,
            "default": 10
          }
        },
        "required": [
          "type",
          "repo"
        ]
      },
      "CloudKind": {
        "type": "string",
        "description": "trust: a website's public trust pages. surface: which AI services a host exposes. mcp: a remote MCP server's tools, prompts and resources. dast: website testing, Response checks and Find more pages over public URLs, incremental.",
        "enum": [
          "trust",
          "surface",
          "mcp",
          "dast"
        ]
      },
      "CloudScanRequest": {
        "type": "object",
        "properties": {
          "kind": {
            "$ref": "#/components/schemas/CloudKind"
          },
          "target": {
            "type": "string",
            "description": "A URL for trust and mcp, a host name for surface (never an IP address). At most 300 characters. Targets resolving to private addresses are refused. dast takes urls instead (or one URL here)."
          },
          "active": {
            "type": "boolean",
            "description": "surface only: also run the active port checks. Needs a domain verified within 30 days whose proof is still in place."
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "maxItems": 25,
            "description": "dast only: 1 to 25 http(s) URLs on at most 3 public host names, default ports. Only these hosts are touched; links elsewhere are never followed."
          },
          "modules": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "passive",
                "crawl"
              ]
            },
            "minItems": 1,
            "description": "dast only: passive (Response checks) and crawl (Find more pages, depth 1); default passive. Any other module is refused with where it runs (attack probes: the CLI's keryn dast scan --active). Per scan at most 100 requests, 1 MB a page, 8 MB in all, 40 s; per organization 1,000 requests an hour, reserved from the plan before anything is sent. An unchanged surface is answered from the stored manifest with zero requests. Usage is metered in shadow, by unique URL template."
          }
        },
        "required": [
          "kind"
        ]
      },
      "CloudScanRow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "$ref": "#/components/schemas/CloudKind"
          },
          "target": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "done",
              "failed"
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "summary": {
            "type": "object",
            "additionalProperties": true,
            "description": "Short typed summary: strings 200 characters, lists 50 items."
          },
          "findings": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "kind",
          "target",
          "active",
          "status",
          "error",
          "summary",
          "findings",
          "created_at"
        ]
      },
      "CloudScan": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CloudScanRow"
          },
          {
            "type": "object",
            "properties": {
              "report": {
                "type": "object",
                "nullable": true,
                "additionalProperties": true,
                "description": "The Keryn result for the scan, capped at 450,000 bytes."
              }
            }
          }
        ]
      },
      "Domain": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "domain": {
            "type": "string"
          },
          "token": {
            "type": "string",
            "description": "Put keryn-verification=<token> in a TXT record on the domain or _keryn.<domain>, or serve the token at https://<domain>/.well-known/keryn-verification.txt."
          },
          "verified_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "method": {
            "type": "string",
            "enum": [
              "dns",
              "well-known"
            ],
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "domain",
          "token",
          "verified_at",
          "method",
          "created_at"
        ]
      },
      "DirectoryToken": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastUsedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "revokedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "status",
          "createdAt",
          "lastUsedAt",
          "expiresAt",
          "revokedAt"
        ]
      },
      "Credits": {
        "type": "object",
        "properties": {
          "balanceCents": {
            "type": "integer"
          },
          "reservedCents": {
            "type": "integer"
          },
          "restrictedCents": {
            "type": "integer",
            "description": "Free-grant credit that cannot pay for builds, pentests or active DAST on unverified domains."
          },
          "grants": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "starter",
                    "promo"
                  ]
                },
                "amountCents": {
                  "type": "integer"
                },
                "expiresAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "expired": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "kind",
                "amountCents",
                "expiresAt",
                "expired"
              ]
            }
          },
          "starter": {
            "type": "string",
            "enum": [
              "available",
              "claimed"
            ]
          }
        },
        "required": [
          "balanceCents",
          "reservedCents",
          "restrictedCents",
          "grants",
          "starter"
        ]
      },
      "JsonRpcMessage": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "id": {
            "description": "Absent for a notification.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "method": {
            "type": "string",
            "description": "For example initialize, ping, tools/list, tools/call."
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "jsonrpc",
          "method"
        ]
      },
      "PairStart": {
        "type": "object",
        "properties": {
          "client": {
            "type": "string",
            "enum": [
              "web",
              "extension",
              "native",
              "cli"
            ]
          },
          "name": {
            "type": "string",
            "description": "Shown to the approver. 60 characters at most."
          }
        },
        "required": [
          "client"
        ]
      },
      "PairStarted": {
        "type": "object",
        "properties": {
          "pairingCode": {
            "type": "string",
            "description": "Secret. Keep it; poll POST /api/pair/token with it."
          },
          "userCode": {
            "type": "string",
            "description": "Show this to the person, for example BCDF-2345."
          },
          "verificationUri": {
            "type": "string",
            "format": "uri"
          },
          "expiresIn": {
            "type": "integer",
            "description": "Seconds."
          },
          "interval": {
            "type": "integer",
            "description": "Seconds between polls."
          }
        },
        "required": [
          "pairingCode",
          "userCode",
          "verificationUri",
          "expiresIn",
          "interval"
        ]
      },
      "PairToken": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "pending"
                ]
              }
            },
            "required": [
              "status"
            ]
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "approved"
                ]
              },
              "token": {
                "type": "string",
                "description": "Worker token. Returned once."
              },
              "deviceId": {
                "type": "string",
                "format": "uuid"
              },
              "organizationId": {
                "type": "string"
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "status",
              "token",
              "deviceId",
              "organizationId",
              "expiresAt"
            ]
          }
        ]
      },
      "PairInspect": {
        "type": "object",
        "properties": {
          "client": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "client",
          "name",
          "requestedAt"
        ]
      },
      "StepUp": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Six-digit TOTP code.",
            "pattern": "^\\d{6}$"
          },
          "requestHash": {
            "type": "string",
            "description": "SHA-256 hex of the request being authorized.",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "code",
          "requestHash"
        ]
      }
    }
  }
}
