{
  "openapi": "3.1.1",
  "info": {
    "title": "Backbone API",
    "version": "1.0.0",
    "summary": "Shared, multi-tenant and multi-product services every product plugs into.",
    "description": "Contract of the backbone (deployed once): accounts and organizations (the OIDC issuer itself is standard OpenID Connect at `/.well-known/openid-configuration`), notifications (e-mail, SMS), webhook delivery, audit, usage metering and feature flags.\n\nConventions (`docs/api-standards.md`, enforced by `contracts/.spectral.yaml`): camelCase JSON, UTC ISO-8601 times, prefixed ULID ids, RFC 9457 problems with a stable `code`, cursor pagination (`items`, `nextCursor`), `Idempotency-Key` on creates, `ETag`/`If-Match` on updates, IETF `RateLimit` headers.\n\nCallers: users through a product BFF (access token with `aud` = product + `backbone`), product services (client credentials) and organization API keys. Organization-scoped resources live under `/v1/organizations/{organizationId}`; organizations the caller cannot see answer `404`.\n\nEntitlements are enforced: the issuer only issues user tokens for a product (OIDC client) in an organization with an `active` or `trialing` entitlement for that product (the token carries it as the `ent` claim), and a product's service identity (client credentials) only sees organizations entitled to its product, and users who are members of one (others answer `404`). See `docs/identity.md`.",
    "contact": {
      "name": "Platform team"
    },
    "license": {
      "name": "Proprietary",
      "identifier": "LicenseRef-Proprietary"
    }
  },
  "servers": [
    {
      "url": "http://localhost:8081",
      "description": "Local backbone (`pnpm dev` in the backbone repo)"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "system",
      "description": "Health and readiness probes."
    },
    {
      "name": "me",
      "description": "The calling principal and their preferences."
    },
    {
      "name": "organizations",
      "description": "Tenants and their product entitlements."
    },
    {
      "name": "members",
      "description": "Memberships and invitations."
    },
    {
      "name": "api-keys",
      "description": "Organization API keys (machine access to the backbone and to products)."
    },
    {
      "name": "products",
      "description": "Registered products (OIDC clients)."
    },
    {
      "name": "users",
      "description": "Users (platform administration)."
    },
    {
      "name": "notifications",
      "description": "E-mail and SMS through provider adapters, templates, preferences."
    },
    {
      "name": "webhooks",
      "description": "Standard Webhooks delivery of backbone and product events to tenants."
    },
    {
      "name": "audit",
      "description": "Central, append-only audit log."
    },
    {
      "name": "usage",
      "description": "Usage metering intake and reports."
    },
    {
      "name": "budgets",
      "description": "Monthly budgets per organization (and per product resource) with a warning level and a hard stop that products enforce (`402 budget_exceeded`)."
    },
    {
      "name": "feature-flags",
      "description": "Feature flags per product, organization and plan."
    }
  ],
  "paths": {
    "/health/live": {
      "get": {
        "operationId": "getLiveness",
        "tags": [
          "system"
        ],
        "summary": "Liveness probe",
        "security": [],
        "responses": {
          "200": {
            "description": "Running.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/health/ready": {
      "get": {
        "operationId": "getReadiness",
        "tags": [
          "system"
        ],
        "summary": "Readiness probe",
        "description": "`200` when every enabled dependency answers, `503` (same body) otherwise.",
        "security": [],
        "responses": {
          "200": {
            "description": "Ready.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/me": {
      "get": {
        "operationId": "getMe",
        "tags": [
          "me"
        ],
        "summary": "The calling principal",
        "description": "User, service or API key; the active organization comes from the token's `tid` claim (or the key).",
        "responses": {
          "200": {
            "description": "The principal.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "patch": {
        "operationId": "updateMe",
        "tags": [
          "me"
        ],
        "summary": "Update my profile",
        "description": "Users only.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/MeUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/me/organizations": {
      "get": {
        "operationId": "listMyOrganizations",
        "tags": [
          "me"
        ],
        "summary": "Organizations I belong to",
        "description": "With a user token issued to a product, only organizations entitled to that product (`active` or `trialing`) are listed, so the product's organization switcher never offers an organization the issuer would refuse.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of organizations with my role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/me/notification-preferences": {
      "get": {
        "operationId": "getMyNotificationPreferences",
        "tags": [
          "me"
        ],
        "summary": "My notification preferences",
        "responses": {
          "200": {
            "description": "Preferences per category and channel, plus quiet hours.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationPreferences"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "put": {
        "operationId": "replaceMyNotificationPreferences",
        "tags": [
          "me"
        ],
        "summary": "Replace my notification preferences",
        "description": "Transactional categories cannot be disabled (`422 category_required`).",
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NotificationPreferencesUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationPreferences"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations": {
      "post": {
        "operationId": "createOrganization",
        "tags": [
          "organizations"
        ],
        "summary": "Create an organization",
        "description": "Users only; the caller becomes `owner`. Publishes `backbone.fact.organization.created`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "getOrganization",
        "tags": [
          "organizations"
        ],
        "summary": "Get an organization",
        "security": [
          {
            "bearerAuth": [
              "organizations:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "The organization.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "patch": {
        "operationId": "updateOrganization",
        "tags": [
          "organizations"
        ],
        "summary": "Update an organization",
        "security": [
          {
            "bearerAuth": [
              "organizations:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/members": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "listMembers",
        "tags": [
          "members"
        ],
        "summary": "Members of an organization",
        "security": [
          {
            "bearerAuth": [
              "members:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of members.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemberPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/members/{memberId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/MemberIdPath"
        }
      ],
      "patch": {
        "operationId": "updateMember",
        "tags": [
          "members"
        ],
        "summary": "Change a member's role",
        "description": "An organization always keeps an owner (`409 last_owner`). Publishes `backbone.fact.membership.changed`.",
        "security": [
          {
            "bearerAuth": [
              "members:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/MemberUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Member"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "delete": {
        "operationId": "removeMember",
        "tags": [
          "members"
        ],
        "summary": "Remove a member",
        "description": "Publishes `backbone.fact.membership.removed`; products drop their projections.",
        "security": [
          {
            "bearerAuth": [
              "members:write"
            ]
          }
        ],
        "responses": {
          "204": {
            "description": "Removed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/invitations": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "listInvitations",
        "tags": [
          "members"
        ],
        "summary": "Pending invitations",
        "security": [
          {
            "bearerAuth": [
              "members:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of invitations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvitationPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "post": {
        "operationId": "createInvitation",
        "tags": [
          "members"
        ],
        "summary": "Invite someone by e-mail",
        "description": "Sends the `invitation` notification (e-mail) through the notifications module. Expires after 7 days.",
        "security": [
          {
            "bearerAuth": [
              "members:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvitationCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Invited.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invitation"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/invitations/{invitationId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/InvitationIdPath"
        }
      ],
      "delete": {
        "operationId": "revokeInvitation",
        "tags": [
          "members"
        ],
        "summary": "Revoke an invitation",
        "security": [
          {
            "bearerAuth": [
              "members:write"
            ]
          }
        ],
        "responses": {
          "204": {
            "description": "Revoked."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/invitations/accept": {
      "post": {
        "operationId": "acceptInvitation",
        "tags": [
          "members"
        ],
        "summary": "Accept an invitation",
        "description": "Users only. The signed-in user's verified e-mail must match the invitation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvitationAccept"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Now a member.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Membership"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/branding": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "getResolvedBranding",
        "tags": [
          "organizations"
        ],
        "summary": "Branding to apply for a product in this organization",
        "description": "The organization's white-label settings layered over the product's branding and the brand's (login host) defaults. `showPoweredBy` is false only when the organization hides it and its entitlement for the product has the `white_label` feature. Products render their UI, e-mails and embeds with it (ADR 0032).",
        "security": [
          {
            "bearerAuth": [
              "organizations:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "productId",
            "in": "query",
            "description": "Defaults to the calling product (service token or a user token issued to a product).",
            "schema": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The effective branding.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResolvedBranding"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/entitlements": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "listEntitlements",
        "tags": [
          "organizations"
        ],
        "summary": "Products this organization may use",
        "description": "A product's service identity sees only its own product's entitlement.",
        "security": [
          {
            "bearerAuth": [
              "organizations:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Entitlements.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntitlementList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/entitlements/{productId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/ProductIdPath"
        }
      ],
      "put": {
        "operationId": "setEntitlement",
        "tags": [
          "organizations"
        ],
        "summary": "Grant or change a product entitlement",
        "description": "Platform admins (or the `entitlements grant|revoke` CLI verbs). Publishes `backbone.fact.entitlement.changed` with `change` = `granted`, `updated` or `revoked`. Only `active` and `trialing` let members sign in to the product; `suspended` and `cancelled` make the issuer refuse new tokens and refreshes for this organization and product.",
        "security": [
          {
            "bearerAuth": [
              "platform:admin"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EntitlementUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Entitlement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/api-keys": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "listApiKeys",
        "tags": [
          "api-keys"
        ],
        "summary": "API keys of an organization",
        "security": [
          {
            "bearerAuth": [
              "api-keys:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ApiKeyKind"
            }
          },
          {
            "name": "productId",
            "in": "query",
            "description": "Keys issued in this product's key namespace.",
            "schema": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "post": {
        "operationId": "createApiKey",
        "tags": [
          "api-keys"
        ],
        "summary": "Create an API key",
        "description": "Users only (`403 user_required` otherwise). The token is shown once (`secret`); only its SHA-256 is kept (a publishable key's token stays readable as `publishableKey`: it is public by design).\n\n- **Secret keys** (`kind: secret`, default) authenticate servers. Backbone scopes must be a subset of the creator's; `api-keys:write` and `members:write` can never be put on a key (`scope_not_allowed`).\n- **Publishable keys** (`kind: publishable`) sit in web pages (an embeddable widget): no scopes, bound to `resourceIds` (e.g. the agent the page embeds) and an `allowedOrigins` list; they only work on a product's public endpoints, which verify them with the browser's `Origin`.\n- `productId` issues the key in that product's key namespace (`<apiKeyPrefix>_live_…`, `_test_`, `_pub_`), restricts it to that product and needs an active entitlement; without it the key is a backbone key (`bb_`).\n- `rateLimitPerMinute` gives the key its own request limit (the `RateLimit-Policy` is then `\"api-key\"`).",
        "security": [
          {
            "bearerAuth": [
              "api-keys:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiKeyCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyWithSecret"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/api-keys/{apiKeyId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/ApiKeyIdPath"
        }
      ],
      "get": {
        "operationId": "getApiKey",
        "tags": [
          "api-keys"
        ],
        "summary": "Get an API key",
        "security": [
          {
            "bearerAuth": [
              "api-keys:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "The key (never its secret).",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKey"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "patch": {
        "operationId": "updateApiKey",
        "tags": [
          "api-keys"
        ],
        "summary": "Change an API key",
        "description": "Users only. Name, scopes (secret keys), resource and origin bindings, and the per-key rate limit. Publishes `backbone.fact.api-key.updated` so products drop cached verifications. Revoked keys answer `409 revoked`.",
        "security": [
          {
            "bearerAuth": [
              "api-keys:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/ApiKeyUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKey"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "delete": {
        "operationId": "revokeApiKey",
        "tags": [
          "api-keys"
        ],
        "summary": "Revoke an API key",
        "description": "Immediate; publishes `backbone.fact.api-key.revoked` so products drop cached verifications.",
        "security": [
          {
            "bearerAuth": [
              "api-keys:write"
            ]
          }
        ],
        "responses": {
          "204": {
            "description": "Revoked."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/api-keys/verify": {
      "post": {
        "operationId": "verifyApiKey",
        "tags": [
          "api-keys"
        ],
        "summary": "Verify an API key (for products)",
        "description": "Product services call this when a request carries an API key (`<prefix>_live_…`, `_test_`, `_pub_`). A key is valid for the calling product only when it is usable (not revoked or expired), not restricted to other products and its organization is entitled to the product; otherwise `valid: false` with a `reason`.\n\nFor a publishable key pass the browser's `origin` (it must be in the key's `allowedOrigins`) and the `resourceId` the call is about (it must be one of the key's `resourceIds`). Secret keys ignore `origin`.\n\nCaching (resource-server verification): cache a positive answer for `cacheSeconds` (60), a negative one for `cacheSeconds` (10); when the backbone cannot be reached, keep serving a positive answer for up to `staleIfErrorSeconds` (900) after it was fetched. `backbone.fact.api-key.revoked` and `backbone.fact.api-key.updated` evict at once.",
        "security": [
          {
            "bearerAuth": [
              "api-keys:verify"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiKeyVerifyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyVerification"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/products": {
      "get": {
        "operationId": "listProducts",
        "tags": [
          "products"
        ],
        "summary": "Registered products",
        "description": "Everyone signed in can list products (names, ids, scopes).",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of products.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "post": {
        "operationId": "registerProduct",
        "tags": [
          "products"
        ],
        "summary": "Register a product",
        "description": "Platform admins (or the `products register` CLI verb). Creates the product's OIDC client (confidential, code + PKCE + client credentials); the client secret is shown once. `brand` binds the client to one login host (per-brand issuer); `branding` themes the login page and e-mails for this product.",
        "security": [
          {
            "bearerAuth": [
              "platform:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registered.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductWithSecret"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/products/{productId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProductIdPath"
        }
      ],
      "get": {
        "operationId": "getProduct",
        "tags": [
          "products"
        ],
        "summary": "Get a product",
        "responses": {
          "200": {
            "description": "The product.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "patch": {
        "operationId": "updateProduct",
        "tags": [
          "products"
        ],
        "summary": "Update a product",
        "security": [
          {
            "bearerAuth": [
              "platform:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/ProductUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/products/{productId}/secret/rotate": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProductIdPath"
        }
      ],
      "post": {
        "operationId": "rotateProductSecret",
        "tags": [
          "products"
        ],
        "summary": "Rotate the client secret",
        "security": [
          {
            "bearerAuth": [
              "platform:admin"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "New secret (shown once); the previous one stays valid for 24 h.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductWithSecret"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/users": {
      "get": {
        "operationId": "listUsers",
        "tags": [
          "users"
        ],
        "summary": "Users (platform admins)",
        "security": [
          {
            "bearerAuth": [
              "platform:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of users.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/users/{userId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/UserIdPath"
        }
      ],
      "get": {
        "operationId": "getUser",
        "tags": [
          "users"
        ],
        "summary": "Get a user",
        "description": "Platform admins, or services resolving a user they received in a fact. A product's service identity only sees users who are members of an organization entitled to its product (others answer `404`).",
        "security": [
          {
            "bearerAuth": [
              "users:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The user.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/notifications": {
      "post": {
        "operationId": "sendNotification",
        "tags": [
          "notifications"
        ],
        "summary": "Send a notification",
        "description": "Products ask the backbone to notify someone; they never talk to e-mail/SMS providers. Idempotent with `Idempotency-Key` (or send the command `backbone.command.notification.send`). The backbone renders the template (per-organization branding, locale with fallback), applies preferences, unsubscribe, quiet hours and rate limits, routes to the provider configured for the organization/product, retries and fails over, and publishes `backbone.fact.notification.delivered|bounced|failed`. A product's service identity can only notify in organizations entitled to its product (`404 not_found` otherwise). Without a template of its own the product falls back to the backbone's template with the same key (e.g. `invitation`).",
        "security": [
          {
            "bearerAuth": [
              "notifications:send"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NotificationCreate"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Notification"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "get": {
        "operationId": "listNotifications",
        "tags": [
          "notifications"
        ],
        "summary": "Notification log",
        "security": [
          {
            "bearerAuth": [
              "notifications:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "organizationId",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/OrganizationId"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/NotificationStatus"
            }
          },
          {
            "name": "recipientUserId",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/UserId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/notifications/{notificationId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/NotificationIdPath"
        }
      ],
      "get": {
        "operationId": "getNotification",
        "tags": [
          "notifications"
        ],
        "summary": "Get a notification",
        "security": [
          {
            "bearerAuth": [
              "notifications:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "With per-channel deliveries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Notification"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/notification-categories": {
      "get": {
        "operationId": "listNotificationCategories",
        "tags": [
          "notifications"
        ],
        "summary": "Notification categories",
        "description": "Categories users can (or cannot, when `required`) opt out of, per product. Categories come from the `category` of the templates a product registers; `transactional` and `security` are required.",
        "responses": {
          "200": {
            "description": "The catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationCategoryList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/notification-templates": {
      "get": {
        "operationId": "listNotificationTemplates",
        "tags": [
          "notifications"
        ],
        "summary": "Templates",
        "security": [
          {
            "bearerAuth": [
              "notification-templates:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "productId",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          },
          {
            "name": "organizationId",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/OrganizationId"
            }
          },
          {
            "name": "key",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/TemplateKey"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of templates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationTemplatePage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "post": {
        "operationId": "createNotificationTemplate",
        "tags": [
          "notifications"
        ],
        "summary": "Create a template",
        "description": "A template is (key, channel, locale) for a product, optionally overridden per organization. E-mail bodies are MJML with Scriban placeholders; SMS and subjects are Scriban text.",
        "security": [
          {
            "bearerAuth": [
              "notification-templates:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NotificationTemplateCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationTemplate"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/notification-templates/{templateId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/TemplateIdPath"
        }
      ],
      "get": {
        "operationId": "getNotificationTemplate",
        "tags": [
          "notifications"
        ],
        "summary": "Get a template",
        "security": [
          {
            "bearerAuth": [
              "notification-templates:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The template.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationTemplate"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "patch": {
        "operationId": "updateNotificationTemplate",
        "tags": [
          "notifications"
        ],
        "summary": "Update a template",
        "security": [
          {
            "bearerAuth": [
              "notification-templates:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/NotificationTemplateUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationTemplate"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "delete": {
        "operationId": "deleteNotificationTemplate",
        "tags": [
          "notifications"
        ],
        "summary": "Delete a template",
        "security": [
          {
            "bearerAuth": [
              "notification-templates:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatchOptional"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/notification-templates/{templateId}/preview": {
      "parameters": [
        {
          "$ref": "#/components/parameters/TemplateIdPath"
        }
      ],
      "post": {
        "operationId": "previewNotificationTemplate",
        "tags": [
          "notifications"
        ],
        "summary": "Render a template with sample data",
        "security": [
          {
            "bearerAuth": [
              "notification-templates:read"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TemplatePreviewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rendered subject/html/text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplatePreview"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/unsubscribe": {
      "post": {
        "operationId": "unsubscribe",
        "tags": [
          "notifications"
        ],
        "summary": "Unsubscribe (one click)",
        "description": "Public. Target of the `List-Unsubscribe` header (RFC 8058 one-click: form body `List-Unsubscribe=One-Click`) and of the unsubscribe page. The signed token names user, category and channel.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 1024
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "listUnsubscribe": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unsubscribed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnsubscribeResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/provider-callbacks/{provider}/{callbackToken}": {
      "post": {
        "operationId": "receiveProviderCallback",
        "tags": [
          "notifications"
        ],
        "summary": "Delivery status callback from a provider",
        "description": "Public; authenticated by the unguessable `callbackToken` and, where the provider signs requests, by its signature (Twilio `X-Twilio-Signature`, Vonage signed JWT, Postmark basic auth, SES via SNS signature). Bodies are provider-specific.",
        "security": [],
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "ses",
                "postmark",
                "cm",
                "twilio",
                "bird",
                "vonage"
              ]
            }
          },
          {
            "name": "callbackToken",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Accepted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/event-types": {
      "get": {
        "operationId": "listEventTypes",
        "tags": [
          "webhooks"
        ],
        "summary": "Public event catalog",
        "description": "Every event a webhook endpoint can subscribe to: backbone events and the public events of registered products.",
        "parameters": [
          {
            "name": "productId",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventTypeList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/webhook-endpoints": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "listWebhookEndpoints",
        "tags": [
          "webhooks"
        ],
        "summary": "Webhook endpoints",
        "security": [
          {
            "bearerAuth": [
              "webhooks:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of endpoints.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "post": {
        "operationId": "createWebhookEndpoint",
        "tags": [
          "webhooks"
        ],
        "summary": "Add a webhook endpoint",
        "description": "The signing secret (`whsec_…`) is returned once.",
        "security": [
          {
            "bearerAuth": [
              "webhooks:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointWithSecret"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/webhook-endpoints/{endpointId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/EndpointIdPath"
        }
      ],
      "get": {
        "operationId": "getWebhookEndpoint",
        "tags": [
          "webhooks"
        ],
        "summary": "Get a webhook endpoint",
        "security": [
          {
            "bearerAuth": [
              "webhooks:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The endpoint.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "patch": {
        "operationId": "updateWebhookEndpoint",
        "tags": [
          "webhooks"
        ],
        "summary": "Update a webhook endpoint",
        "security": [
          {
            "bearerAuth": [
              "webhooks:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "delete": {
        "operationId": "deleteWebhookEndpoint",
        "tags": [
          "webhooks"
        ],
        "summary": "Delete a webhook endpoint",
        "security": [
          {
            "bearerAuth": [
              "webhooks:write"
            ]
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/webhook-endpoints/{endpointId}/secret/rotate": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/EndpointIdPath"
        }
      ],
      "post": {
        "operationId": "rotateWebhookSecret",
        "tags": [
          "webhooks"
        ],
        "summary": "Rotate the signing secret",
        "description": "The new secret signs immediately; the previous one keeps signing as a second signature for 24 h.",
        "security": [
          {
            "bearerAuth": [
              "webhooks:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "New secret (shown once).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointWithSecret"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/webhook-endpoints/{endpointId}/deliveries": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/EndpointIdPath"
        }
      ],
      "get": {
        "operationId": "listWebhookDeliveries",
        "tags": [
          "webhooks"
        ],
        "summary": "Delivery log",
        "security": [
          {
            "bearerAuth": [
              "webhooks:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/WebhookDeliveryStatus"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/webhook-endpoints/{endpointId}/deliveries/{deliveryId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/EndpointIdPath"
        },
        {
          "$ref": "#/components/parameters/DeliveryIdPath"
        }
      ],
      "get": {
        "operationId": "getWebhookDelivery",
        "tags": [
          "webhooks"
        ],
        "summary": "One delivery with its payload and attempts",
        "description": "The payload as sent, every attempt (time, status, duration, error) and the start of the receiver's last response. Deliveries are kept 30 days.",
        "security": [
          {
            "bearerAuth": [
              "webhooks:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/webhook-endpoints/{endpointId}/test": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/EndpointIdPath"
        }
      ],
      "post": {
        "operationId": "sendTestWebhook",
        "tags": [
          "webhooks"
        ],
        "summary": "Send a test event",
        "description": "Queues a sample (`data.test = true`, type `webhook.test` or the given event type) to this endpoint only, signed like any delivery.",
        "security": [
          {
            "bearerAuth": [
              "webhooks:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookTestRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/redeliver": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/EndpointIdPath"
        },
        {
          "$ref": "#/components/parameters/DeliveryIdPath"
        }
      ],
      "post": {
        "operationId": "redeliverWebhook",
        "tags": [
          "webhooks"
        ],
        "summary": "Send a delivery again",
        "description": "Same `webhook-id`, so receivers can deduplicate.",
        "security": [
          {
            "bearerAuth": [
              "webhooks:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "202": {
            "description": "Queued.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/audit-events": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "listAuditEvents",
        "tags": [
          "audit"
        ],
        "summary": "Audit log",
        "description": "Newest first. Backbone actions plus what products record (command `backbone.command.audit.record` or POST).",
        "security": [
          {
            "bearerAuth": [
              "audit:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "productId",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          },
          {
            "name": "action",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$",
              "maxLength": 120
            }
          },
          {
            "name": "actorId",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          },
          {
            "name": "occurredAfter",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "occurredBefore",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of audit events.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditEventPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/audit-events": {
      "post": {
        "operationId": "recordAuditEvent",
        "tags": [
          "audit"
        ],
        "summary": "Record an audit event (products)",
        "description": "Service principals. Idempotent on `id` (the producer's event id).",
        "security": [
          {
            "bearerAuth": [
              "audit:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditEventCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Recorded.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditEvent"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/usage-records": {
      "post": {
        "operationId": "recordUsage",
        "tags": [
          "usage"
        ],
        "summary": "Record usage (products)",
        "description": "Service principals. Idempotent on `id`. Batch up to 500 records.",
        "security": [
          {
            "bearerAuth": [
              "usage:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UsageRecordBatch"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageRecordBatchResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/usage": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "getUsage",
        "tags": [
          "usage"
        ],
        "summary": "Usage report",
        "security": [
          {
            "bearerAuth": [
              "usage:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "granularity",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "hour",
                "day",
                "month"
              ],
              "default": "day"
            }
          },
          {
            "name": "productId",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          },
          {
            "name": "meter",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/MeterKey"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Quantities per meter and bucket.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageReport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/budgets": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "listBudgets",
        "tags": [
          "budgets"
        ],
        "summary": "Budgets of an organization with this month's usage",
        "security": [
          {
            "bearerAuth": [
              "budgets:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "productId",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of budgets.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BudgetPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "post": {
        "operationId": "createBudget",
        "tags": [
          "budgets"
        ],
        "summary": "Create a monthly budget",
        "description": "A limit on one meter of one product per calendar month (in `timeZone`), optionally for one product resource (`resourceId`, e.g. an agent). Money budgets are budgets on a cost meter the product records (e.g. `belvoy.provider_cost_usd`). At `warnPercent` and at the limit the backbone publishes `backbone.fact.budget.alerted` once per level and month (also delivered as a webhook). With `hardStop`, products refuse new billable work while the budget is used up (`GET …/budget-check`, `402 budget_exceeded`).",
        "security": [
          {
            "bearerAuth": [
              "budgets:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BudgetCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Budget"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/budgets/{budgetId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        },
        {
          "$ref": "#/components/parameters/BudgetIdPath"
        }
      ],
      "get": {
        "operationId": "getBudget",
        "tags": [
          "budgets"
        ],
        "summary": "Get a budget with this month's usage",
        "security": [
          {
            "bearerAuth": [
              "budgets:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The budget.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Budget"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "patch": {
        "operationId": "updateBudget",
        "tags": [
          "budgets"
        ],
        "summary": "Change a budget",
        "description": "Changing the limit or the warning share lets the budget alert again this month.",
        "security": [
          {
            "bearerAuth": [
              "budgets:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/BudgetUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Budget"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "delete": {
        "operationId": "deleteBudget",
        "tags": [
          "budgets"
        ],
        "summary": "Delete a budget",
        "security": [
          {
            "bearerAuth": [
              "budgets:write"
            ]
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/organizations/{organizationId}/budget-check": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationIdPath"
        }
      ],
      "get": {
        "operationId": "checkBudgets",
        "tags": [
          "budgets"
        ],
        "summary": "May a product start billable work?",
        "description": "The enforcement question (products ask before starting a call, a job, …; cache it briefly or follow `backbone.fact.budget.alerted`). `allowed: false` while a hard-stop budget of the product (organization-wide, or of `resourceId`) or a plan limit is used up; the product then answers `402 budget_exceeded` with the `blocking` budgets in the problem. Plan limits are entitlement features `limits.<meter>` (a number per UTC month, always hard). Running work is never cut off. Product services may call this with `usage:write`.",
        "security": [
          {
            "bearerAuth": [
              "budgets:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "productId",
            "in": "query",
            "description": "Defaults to the calling product (service tokens).",
            "schema": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          },
          {
            "name": "meter",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/MeterKey"
            }
          },
          {
            "name": "resourceId",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The verdict and the budgets considered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BudgetCheck"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/meters": {
      "get": {
        "operationId": "listMeters",
        "tags": [
          "usage"
        ],
        "summary": "Meter catalog",
        "parameters": [
          {
            "name": "productId",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Meters registered by the backbone and products.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/feature-flags/evaluate": {
      "get": {
        "operationId": "evaluateFeatureFlags",
        "tags": [
          "feature-flags"
        ],
        "summary": "Evaluate flags",
        "description": "For an organization and product (defaults: the token's `tid` and `aud`).",
        "parameters": [
          {
            "name": "organizationId",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/OrganizationId"
            }
          },
          {
            "name": "productId",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Evaluated flags.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagEvaluationList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/feature-flags": {
      "get": {
        "operationId": "listFeatureFlags",
        "tags": [
          "feature-flags"
        ],
        "summary": "Flag definitions",
        "security": [
          {
            "bearerAuth": [
              "flags:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of flags.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/feature-flags/{flagKey}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/FlagKeyPath"
        }
      ],
      "put": {
        "operationId": "upsertFeatureFlag",
        "tags": [
          "feature-flags"
        ],
        "summary": "Create or replace a flag",
        "security": [
          {
            "bearerAuth": [
              "flags:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfMatchOptional"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeatureFlagUpsert"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlag"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    }
  },
  "webhooks": {
    "backbone.organization.created": {
      "post": {
        "operationId": "onOrganizationCreated",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.organization.created",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.organization.created"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.organization.created.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.organization.updated": {
      "post": {
        "operationId": "onOrganizationUpdated",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.organization.updated",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.organization.updated"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.organization.updated.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.membership.added": {
      "post": {
        "operationId": "onMembershipAdded",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.membership.added",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.membership.added"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.membership.added.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.membership.changed": {
      "post": {
        "operationId": "onMembershipChanged",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.membership.changed",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.membership.changed"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.membership.changed.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.membership.removed": {
      "post": {
        "operationId": "onMembershipRemoved",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.membership.removed",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.membership.removed"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.membership.removed.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.invitation.created": {
      "post": {
        "operationId": "onInvitationCreated",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.invitation.created",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.invitation.created"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.invitation.created.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.api-key.created": {
      "post": {
        "operationId": "onApiKeyCreated",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.api-key.created",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.api-key.created"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.api-key.created.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.api-key.revoked": {
      "post": {
        "operationId": "onApiKeyRevoked",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.api-key.revoked",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.api-key.revoked"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.api-key.revoked.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.api-key.updated": {
      "post": {
        "operationId": "onApiKeyUpdated",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.api-key.updated",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.api-key.updated"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.api-key.updated.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.budget.alerted": {
      "post": {
        "operationId": "onBudgetAlerted",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.budget.alerted",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.budget.alerted"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.budget.alerted.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.notification.delivered": {
      "post": {
        "operationId": "onNotificationDelivered",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.notification.delivered",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.notification.delivered"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.notification.delivered.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.notification.bounced": {
      "post": {
        "operationId": "onNotificationBounced",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.notification.bounced",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.notification.bounced"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.notification.bounced.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    },
    "backbone.notification.failed": {
      "post": {
        "operationId": "onNotificationFailed",
        "tags": [
          "webhooks"
        ],
        "summary": "backbone.notification.failed",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/webhook-envelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "backbone.notification.failed"
                      },
                      "data": {
                        "$ref": "#/components/schemas/backbone.notification.failed.v1"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges the delivery."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT or bb_ API key",
        "description": "Access token issued by the backbone's OIDC issuer (users via a product BFF, services via client credentials) or an organization API key (`bb_live_…`, `bb_test_…`). Role/scope names are listed per operation (OpenAPI 3.1 allows them for non-OAuth schemes)."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Same key + same body within 24 h replays the stored response (`Idempotent-Replayed: true`); same key + different body → `422 idempotency_key_reused`; while the first request runs → `409 idempotency_key_in_use`.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "pattern": "^[\\x21-\\x7E]+$"
        }
      },
      "IfMatch": {
        "name": "If-Match",
        "in": "header",
        "required": true,
        "description": "The `ETag` you read. Missing → `428`; stale → `412`.",
        "schema": {
          "type": "string",
          "maxLength": 64
        }
      },
      "IfMatchOptional": {
        "name": "If-Match",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 64
        }
      },
      "IfNoneMatch": {
        "name": "If-None-Match",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 64
        }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "Opaque cursor from `nextCursor`.",
        "schema": {
          "type": "string",
          "maxLength": 512,
          "pattern": "^[A-Za-z0-9_-]+$"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      },
      "OrganizationIdPath": {
        "name": "organizationId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/OrganizationId"
        }
      },
      "MemberIdPath": {
        "name": "memberId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/MemberId"
        }
      },
      "InvitationIdPath": {
        "name": "invitationId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/InvitationId"
        }
      },
      "ApiKeyIdPath": {
        "name": "apiKeyId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/ApiKeyId"
        }
      },
      "ProductIdPath": {
        "name": "productId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/ProductSlug"
        }
      },
      "UserIdPath": {
        "name": "userId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/UserId"
        }
      },
      "NotificationIdPath": {
        "name": "notificationId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/NotificationId"
        }
      },
      "TemplateIdPath": {
        "name": "templateId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/TemplateId"
        }
      },
      "EndpointIdPath": {
        "name": "endpointId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/WebhookEndpointId"
        }
      },
      "DeliveryIdPath": {
        "name": "deliveryId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/WebhookMessageId"
        }
      },
      "BudgetIdPath": {
        "name": "budgetId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/BudgetId"
        }
      },
      "FlagKeyPath": {
        "name": "flagKey",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/FlagKey"
        }
      }
    },
    "headers": {
      "ETag": {
        "description": "Strong validator (the resource version).",
        "schema": {
          "type": "string"
        }
      },
      "Location": {
        "description": "URL of the created resource or the operation to poll.",
        "schema": {
          "type": "string"
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "IdempotentReplayed": {
        "description": "`true` when replayed for a repeated `Idempotency-Key`.",
        "schema": {
          "type": "string",
          "enum": [
            "true"
          ]
        }
      },
      "RateLimit": {
        "description": "IETF RateLimit header field, e.g. `\"default\";r=598;t=42`.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimitPolicy": {
        "description": "IETF RateLimit-Policy header field, e.g. `\"default\";q=600;w=60`.",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "Problem": {
        "description": "Error (RFC 9457 problem details).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Malformed request or invalid query parameters (`bad_request`, `malformed_json`, `invalid_cursor`, `invalid_parameter`).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, invalid, expired or revoked credentials (`unauthenticated`, `invalid_api_key`).",
        "headers": {
          "WWW-Authenticate": {
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Not allowed (`insufficient_scope`, `forbidden`, `user_required`, `not_entitled`, `publishable_key` = a publishable key used as a bearer token, `white_label_required`).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such resource, or not visible to the caller (`not_found`).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Conflict": {
        "description": "Conflicts with the current state (`conflict`, `idempotency_key_in_use`, `last_owner`, `already_member`).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "PreconditionFailed": {
        "description": "`If-Match` does not match (`version_mismatch`).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "PreconditionRequired": {
        "description": "`If-Match` is required (`precondition_required`).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "UnprocessableContent": {
        "description": "Well-formed but invalid (`validation_failed` with `errors[]`, `idempotency_key_reused`).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limited (`rate_limited`).",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "NotModified": {
        "description": "Matches `If-None-Match`.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/ETag"
          }
        }
      }
    },
    "schemas": {
      "OrganizationId": {
        "type": "string",
        "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "UserId": {
        "type": "string",
        "pattern": "^usr_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "MemberId": {
        "type": "string",
        "pattern": "^mem_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "InvitationId": {
        "type": "string",
        "pattern": "^inv_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "ApiKeyId": {
        "type": "string",
        "pattern": "^key_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "NotificationId": {
        "type": "string",
        "pattern": "^ntf_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "DeliveryId": {
        "type": "string",
        "pattern": "^dlv_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "TemplateId": {
        "type": "string",
        "pattern": "^tpl_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "WebhookEndpointId": {
        "type": "string",
        "pattern": "^whep_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "WebhookMessageId": {
        "type": "string",
        "pattern": "^msg_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "AuditEventId": {
        "type": "string",
        "pattern": "^aud_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "EventId": {
        "type": "string",
        "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "BudgetId": {
        "type": "string",
        "pattern": "^bud_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "ProductSlug": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]{1,30}$",
        "examples": [
          "notes-demo"
        ],
        "description": "Product id (slug)."
      },
      "FlagKey": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$",
        "maxLength": 100
      },
      "TemplateKey": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$",
        "maxLength": 100,
        "examples": [
          "invitation",
          "note.comment-added"
        ]
      },
      "MeterKey": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$",
        "examples": [
          "notes.created"
        ]
      },
      "Locale": {
        "type": "string",
        "pattern": "^[a-z]{2}(-[A-Z]{2})?$",
        "examples": [
          "nl",
          "en",
          "nl-NL"
        ]
      },
      "Cursor": {
        "type": [
          "string",
          "null"
        ],
        "description": "Opaque; pass it back unchanged. `null` = no more items."
      },
      "Scope": {
        "type": "string",
        "description": "A backbone scope (`organizations:read`, `organizations:write`, `members:read`, `members:write`, `api-keys:read`, `api-keys:write`, `api-keys:verify`, `webhooks:read`, `webhooks:write`, `audit:read`, `audit:write`, `usage:read`, `usage:write`, `budgets:read`, `budgets:write`, `notifications:send`, `notifications:read`, `notification-templates:read`, `notification-templates:write`, `flags:read`, `flags:write`, `users:read`, `platform:admin`) or a product scope `<productId>:<resource>:<action>`.",
        "pattern": "^([a-z][a-z0-9-]{1,30}:)?[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$",
        "examples": [
          "organizations:read",
          "organizations:write",
          "members:read"
        ]
      },
      "Role": {
        "type": "string",
        "enum": [
          "owner",
          "admin",
          "member",
          "viewer"
        ]
      },
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "code"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "minimum": 100,
            "maximum": 599
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*$"
          },
          "traceId": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "pointer",
                "detail"
              ],
              "properties": {
                "pointer": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                },
                "code": {
                  "type": "string"
                }
              }
            }
          }
        },
        "additionalProperties": true,
        "description": "RFC 9457 problem details with a stable `code`."
      },
      "Health": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "down"
            ]
          },
          "checks": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "required": [
                "status"
              ],
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "ok",
                    "degraded",
                    "down"
                  ]
                },
                "detail": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Actor": {
        "type": "object",
        "required": [
          "type",
          "id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "user",
              "apiKey",
              "service",
              "system"
            ]
          },
          "id": {
            "type": "string"
          },
          "displayName": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "User": {
        "type": "object",
        "required": [
          "id",
          "email",
          "name",
          "emailVerified",
          "createdAt",
          "version"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UserId"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "emailVerified": {
            "type": "boolean"
          },
          "name": {
            "type": "string"
          },
          "pictureUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "locale": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Locale"
              },
              {
                "type": "null"
              }
            ]
          },
          "timeZone": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "Europe/Amsterdam"
            ]
          },
          "phoneNumber": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\+[1-9][0-9]{6,14}$",
            "description": "E.164; used for SMS."
          },
          "isPlatformAdmin": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "UserPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/User"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "MeUpdate": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "locale": {
            "$ref": "#/components/schemas/Locale"
          },
          "timeZone": {
            "type": "string",
            "maxLength": 64
          },
          "phoneNumber": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\+[1-9][0-9]{6,14}$"
          }
        }
      },
      "Me": {
        "type": "object",
        "required": [
          "principal",
          "scopes"
        ],
        "properties": {
          "principal": {
            "type": "object",
            "required": [
              "type",
              "id"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "user",
                  "apiKey",
                  "service"
                ]
              },
              "id": {
                "type": "string"
              },
              "displayName": {
                "type": "string"
              }
            }
          },
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "organization": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/OrganizationSummary"
              },
              {
                "type": "null"
              }
            ]
          },
          "role": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Role"
              },
              {
                "type": "null"
              }
            ]
          },
          "productId": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ProductSlug"
              },
              {
                "type": "null"
              }
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          }
        }
      },
      "Branding": {
        "type": "object",
        "description": "The organization's white-label settings (ADR 0032). All optional; empty values inherit the product's branding, then the brand's. Replaced as a whole by `updateOrganization`.",
        "additionalProperties": false,
        "properties": {
          "displayName": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 40,
            "description": "Replaces the product's name in the product UI, e-mails and embeds."
          },
          "primaryColor": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^#[0-9a-fA-F]{6}$"
          },
          "accentColor": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^#[0-9a-fA-F]{6}$",
            "description": "Focus rings, links, switches."
          },
          "logoUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048,
            "description": "Logo for light backgrounds."
          },
          "logoDarkUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048,
            "description": "Logo for dark backgrounds."
          },
          "faviconUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048
          },
          "emailSenderName": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 60,
            "pattern": "^[^\\r\\n<>\",;]*$",
            "description": "Display name of notification e-mails (the sending address stays the brand's)."
          },
          "supportUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048
          },
          "websiteUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048,
            "description": "Where \"Powered by\" and the product's footer link."
          },
          "hidePoweredBy": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Remove \"Powered by …\". Setting it needs an entitlement with the `white_label` feature (`403 white_label_required`); it takes effect per product only where the entitlement has the feature."
          }
        }
      },
      "ResolvedBranding": {
        "type": "object",
        "required": [
          "productId",
          "productName",
          "emailSenderName",
          "showPoweredBy",
          "whiteLabel"
        ],
        "properties": {
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "productName": {
            "type": "string",
            "description": "The organization's display name, else the product's."
          },
          "primaryColor": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^#[0-9a-fA-F]{6}$"
          },
          "accentColor": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^#[0-9a-fA-F]{6}$"
          },
          "backgroundColor": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^#[0-9a-fA-F]{6}$"
          },
          "logoUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "logoDarkUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "faviconUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "emailSenderName": {
            "type": "string"
          },
          "supportUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "websiteUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "privacyUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "termsUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "showPoweredBy": {
            "type": "boolean"
          },
          "whiteLabel": {
            "type": "boolean",
            "description": "The organization's entitlement for this product has the `white_label` feature."
          }
        }
      },
      "OrganizationSummary": {
        "type": "object",
        "required": [
          "id",
          "name",
          "slug"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/OrganizationId"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          }
        }
      },
      "Organization": {
        "type": "object",
        "required": [
          "id",
          "name",
          "slug",
          "branding",
          "defaultLocale",
          "createdAt",
          "updatedAt",
          "version"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/OrganizationId"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "branding": {
            "$ref": "#/components/schemas/Branding"
          },
          "defaultLocale": {
            "$ref": "#/components/schemas/Locale"
          },
          "role": {
            "$ref": "#/components/schemas/Role",
            "description": "The caller's role (absent for services and API keys)."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "OrganizationPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Organization"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "OrganizationCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,39}$"
          },
          "defaultLocale": {
            "$ref": "#/components/schemas/Locale"
          }
        }
      },
      "OrganizationUpdate": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "branding": {
            "$ref": "#/components/schemas/Branding"
          },
          "defaultLocale": {
            "$ref": "#/components/schemas/Locale"
          }
        }
      },
      "Member": {
        "type": "object",
        "required": [
          "id",
          "userId",
          "email",
          "name",
          "role",
          "createdAt",
          "version"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/MemberId"
          },
          "userId": {
            "$ref": "#/components/schemas/UserId"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "name": {
            "type": "string"
          },
          "role": {
            "$ref": "#/components/schemas/Role"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "MemberPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Member"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "MemberUpdate": {
        "type": "object",
        "required": [
          "role"
        ],
        "additionalProperties": false,
        "properties": {
          "role": {
            "$ref": "#/components/schemas/Role"
          }
        }
      },
      "Membership": {
        "type": "object",
        "required": [
          "organization",
          "role"
        ],
        "properties": {
          "organization": {
            "$ref": "#/components/schemas/OrganizationSummary"
          },
          "role": {
            "$ref": "#/components/schemas/Role"
          }
        }
      },
      "Invitation": {
        "type": "object",
        "required": [
          "id",
          "email",
          "role",
          "status",
          "expiresAt",
          "createdAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/InvitationId"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "role": {
            "$ref": "#/components/schemas/Role"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "accepted",
              "revoked",
              "expired"
            ]
          },
          "invitedBy": {
            "$ref": "#/components/schemas/Actor"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "InvitationPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Invitation"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "InvitationCreate": {
        "type": "object",
        "required": [
          "email",
          "role"
        ],
        "additionalProperties": false,
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254
          },
          "role": {
            "$ref": "#/components/schemas/Role"
          },
          "locale": {
            "$ref": "#/components/schemas/Locale"
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug",
            "description": "Product whose branding/link the invitation e-mail uses."
          }
        }
      },
      "InvitationAccept": {
        "type": "object",
        "required": [
          "token"
        ],
        "additionalProperties": false,
        "properties": {
          "token": {
            "type": "string",
            "minLength": 16,
            "maxLength": 512
          }
        }
      },
      "Entitlement": {
        "type": "object",
        "required": [
          "productId",
          "plan",
          "status",
          "updatedAt"
        ],
        "properties": {
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "plan": {
            "type": "string",
            "maxLength": 40,
            "examples": [
              "free",
              "pro"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "trialing",
              "suspended",
              "cancelled"
            ]
          },
          "features": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "boolean",
                "number",
                "string"
              ]
            }
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EntitlementList": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Entitlement"
            }
          }
        }
      },
      "EntitlementUpdate": {
        "type": "object",
        "required": [
          "plan",
          "status"
        ],
        "additionalProperties": false,
        "properties": {
          "plan": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "trialing",
              "suspended",
              "cancelled"
            ]
          },
          "features": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "boolean",
                "number",
                "string"
              ]
            }
          }
        }
      },
      "ApiKeyMode": {
        "type": "string",
        "enum": [
          "live",
          "test"
        ]
      },
      "ApiKeyKind": {
        "type": "string",
        "enum": [
          "secret",
          "publishable"
        ]
      },
      "ApiKeyPrefix": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9]{1,15}$",
        "description": "Key namespace of a product (`bv` → `bv_live_…`, `bv_test_…`, `bv_pub_…`). `bb` is the backbone's.",
        "examples": [
          "bv"
        ]
      },
      "Origin": {
        "type": "string",
        "maxLength": 300,
        "pattern": "^(https://(\\*\\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)*[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(:[0-9]{1,5})?|http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?)$",
        "description": "`https://host[:port]`, `https://*.domain` (any subdomain) or `http://localhost[:port]`; no path, no bare `*`.",
        "examples": [
          "https://www.example.nl",
          "https://*.example.nl"
        ]
      },
      "ResourceId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100,
        "pattern": "^[A-Za-z0-9_.:-]+$",
        "description": "A product resource (e.g. an agent id) a key or a budget is bound to."
      },
      "ApiKey": {
        "type": "object",
        "required": [
          "id",
          "name",
          "kind",
          "mode",
          "prefix",
          "scopes",
          "productIds",
          "resourceIds",
          "allowedOrigins",
          "createdAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ApiKeyId"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "$ref": "#/components/schemas/ApiKeyKind",
            "description": "`secret`: servers, scoped. `publishable`: web pages, no scopes, bound to resources and origins."
          },
          "mode": {
            "$ref": "#/components/schemas/ApiKeyMode"
          },
          "prefix": {
            "type": "string",
            "description": "The start and end of the token for display (`bv_live_7Hk2…Q9xz`)."
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "productIds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductSlug"
            },
            "description": "Products the key works for; empty = all entitled products."
          },
          "productId": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ProductSlug"
              },
              {
                "type": "null"
              }
            ],
            "description": "The product whose key namespace the key was issued in; `null` = a backbone key (`bb_`)."
          },
          "resourceIds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResourceId"
            },
            "description": "Resources the key is bound to; empty = any."
          },
          "allowedOrigins": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Origin"
            },
            "description": "Publishable keys only."
          },
          "rateLimitPerMinute": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "The key's own request limit; `null` = the service default."
          },
          "publishableKey": {
            "type": "string",
            "description": "Publishable keys only (public by design, so it stays readable)."
          },
          "createdBy": {
            "$ref": "#/components/schemas/Actor"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastUsedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "revokedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "ApiKeyWithSecret": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ApiKey"
          },
          {
            "type": "object",
            "required": [
              "secret"
            ],
            "properties": {
              "secret": {
                "type": "string",
                "description": "Shown once."
              }
            }
          }
        ]
      },
      "ApiKeyPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKey"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "ApiKeyCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "additionalProperties": false,
        "description": "Secret keys need `scopes`; publishable keys need `productId`, `resourceIds` and `allowedOrigins` and take no scopes.",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "kind": {
            "$ref": "#/components/schemas/ApiKeyKind"
          },
          "mode": {
            "$ref": "#/components/schemas/ApiKeyMode"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            },
            "maxItems": 100,
            "uniqueItems": true
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "productIds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductSlug"
            },
            "uniqueItems": true
          },
          "resourceIds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResourceId"
            },
            "maxItems": 50,
            "uniqueItems": true
          },
          "allowedOrigins": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Origin"
            },
            "maxItems": 20,
            "uniqueItems": true
          },
          "rateLimitPerMinute": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ApiKeyUpdate": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            },
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true
          },
          "resourceIds": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/ResourceId"
            },
            "maxItems": 50,
            "uniqueItems": true
          },
          "allowedOrigins": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Origin"
            },
            "maxItems": 20,
            "uniqueItems": true
          },
          "rateLimitPerMinute": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 100000
          }
        }
      },
      "ApiKeyVerifyRequest": {
        "type": "object",
        "required": [
          "key"
        ],
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "minLength": 8,
            "maxLength": 200
          },
          "origin": {
            "type": "string",
            "maxLength": 300,
            "description": "The browser's `Origin` (publishable keys)."
          },
          "resourceId": {
            "$ref": "#/components/schemas/ResourceId"
          }
        }
      },
      "ApiKeyVerification": {
        "type": "object",
        "required": [
          "valid",
          "cacheSeconds"
        ],
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "enum": [
              "unknown",
              "revoked",
              "expired",
              "wrong_product",
              "not_entitled",
              "origin_not_allowed",
              "resource_not_allowed"
            ],
            "description": "Why the key is not valid for this call (only when `valid` is false)."
          },
          "apiKeyId": {
            "$ref": "#/components/schemas/ApiKeyId"
          },
          "organizationId": {
            "$ref": "#/components/schemas/OrganizationId"
          },
          "kind": {
            "$ref": "#/components/schemas/ApiKeyKind"
          },
          "mode": {
            "$ref": "#/components/schemas/ApiKeyMode"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "productIds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductSlug"
            }
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "resourceIds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResourceId"
            }
          },
          "allowedOrigins": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Origin"
            }
          },
          "rateLimitPerMinute": {
            "type": "integer",
            "minimum": 1
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "cacheSeconds": {
            "type": "integer",
            "minimum": 0,
            "description": "How long this answer may be cached (positive 60, negative 10)."
          },
          "staleIfErrorSeconds": {
            "type": "integer",
            "minimum": 0,
            "description": "How long after fetching a positive answer may still be used while the backbone cannot be reached."
          }
        }
      },
      "ProductBranding": {
        "type": "object",
        "description": "How the login page and the backbone's e-mails present this product. Unset fields fall back to the brand's settings (login host configuration).",
        "additionalProperties": false,
        "properties": {
          "displayName": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 80,
            "description": "Name shown to users (defaults to the product name)."
          },
          "logoUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048,
            "description": "Absolute https URL of the logo (SVG or PNG, shown at most 48 px high)."
          },
          "primaryColor": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^#[0-9a-fA-F]{6}$",
            "description": "Buttons and links."
          },
          "backgroundColor": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^#[0-9a-fA-F]{6}$",
            "description": "Page background (light theme)."
          },
          "supportUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048
          },
          "privacyUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048
          },
          "termsUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "maxLength": 2048
          }
        }
      },
      "EventTypeAliases": {
        "type": "object",
        "maxProperties": 200,
        "description": "Customer-facing webhook names for this product's public event types (alias → canonical public type), e.g. `conversation.analyzed` → `belvoy.conversation.analyzed`. Tenants may subscribe with either name; a delivery carries the name the endpoint subscribed with (catch-all endpoints get the alias). Aliases are unique across products.",
        "propertyNames": {
          "$ref": "#/components/schemas/EventTypeName"
        },
        "additionalProperties": {
          "$ref": "#/components/schemas/EventTypeName"
        }
      },
      "BrandKey": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]{1,30}$",
        "description": "A brand (login host) configured in the backbone (`Accounts:Brands:<key>`), e.g. `belvoy` for `account.belvoy.nl`.",
        "examples": [
          "belvoy"
        ]
      },
      "Product": {
        "type": "object",
        "required": [
          "id",
          "name",
          "redirectUris",
          "postLogoutRedirectUris",
          "scopes",
          "createdAt",
          "version"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "name": {
            "type": "string"
          },
          "homepageUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "brand": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/BrandKey"
              },
              {
                "type": "null"
              }
            ],
            "description": "The login host this client is bound to; `null` = any host (development)."
          },
          "branding": {
            "$ref": "#/components/schemas/ProductBranding"
          },
          "apiKeyPrefix": {
            "$ref": "#/components/schemas/ApiKeyPrefix"
          },
          "eventTypeAliases": {
            "$ref": "#/components/schemas/EventTypeAliases"
          },
          "redirectUris": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "postLogoutRedirectUris": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "description"
              ],
              "properties": {
                "name": {
                  "$ref": "#/components/schemas/Scope"
                },
                "description": {
                  "type": "string"
                }
              }
            },
            "description": "Scopes the product defines (`<productId>:<resource>:<action>`)."
          },
          "publicEventTypes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Facts of this product that tenants may subscribe to as webhooks."
          },
          "meters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Meter"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "ProductWithSecret": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Product"
          },
          {
            "type": "object",
            "required": [
              "clientId",
              "clientSecret"
            ],
            "properties": {
              "clientId": {
                "type": "string"
              },
              "clientSecret": {
                "type": "string"
              }
            }
          }
        ]
      },
      "ProductPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "ProductCreate": {
        "type": "object",
        "required": [
          "id",
          "name",
          "redirectUris"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "homepageUrl": {
            "type": "string",
            "format": "uri"
          },
          "brand": {
            "$ref": "#/components/schemas/BrandKey"
          },
          "branding": {
            "$ref": "#/components/schemas/ProductBranding"
          },
          "apiKeyPrefix": {
            "$ref": "#/components/schemas/ApiKeyPrefix"
          },
          "eventTypeAliases": {
            "$ref": "#/components/schemas/EventTypeAliases"
          },
          "redirectUris": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "minItems": 1
          },
          "postLogoutRedirectUris": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "description"
              ],
              "properties": {
                "name": {
                  "$ref": "#/components/schemas/Scope"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "publicEventTypes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "meters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Meter"
            }
          }
        }
      },
      "ProductUpdate": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "homepageUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "brand": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/BrandKey"
              },
              {
                "type": "null"
              }
            ]
          },
          "branding": {
            "$ref": "#/components/schemas/ProductBranding"
          },
          "apiKeyPrefix": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ApiKeyPrefix"
              },
              {
                "type": "null"
              }
            ]
          },
          "eventTypeAliases": {
            "$ref": "#/components/schemas/EventTypeAliases"
          },
          "redirectUris": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "minItems": 1
          },
          "postLogoutRedirectUris": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "description"
              ],
              "properties": {
                "name": {
                  "$ref": "#/components/schemas/Scope"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "publicEventTypes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "meters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Meter"
            }
          }
        }
      },
      "Channel": {
        "type": "string",
        "enum": [
          "email",
          "sms"
        ]
      },
      "NotificationStatus": {
        "type": "string",
        "enum": [
          "queued",
          "processing",
          "sent",
          "partially_sent",
          "failed",
          "suppressed"
        ]
      },
      "DeliveryStatus": {
        "type": "string",
        "enum": [
          "queued",
          "deferred",
          "sent",
          "delivered",
          "bounced",
          "failed",
          "suppressed"
        ]
      },
      "Recipient": {
        "type": "object",
        "minProperties": 1,
        "additionalProperties": false,
        "description": "A backbone user (preferred: preferences, locale and time zone apply) or a raw address.",
        "properties": {
          "userId": {
            "$ref": "#/components/schemas/UserId"
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254
          },
          "phoneNumber": {
            "type": "string",
            "pattern": "^\\+[1-9][0-9]{6,14}$"
          },
          "locale": {
            "$ref": "#/components/schemas/Locale"
          },
          "timeZone": {
            "type": "string",
            "maxLength": 64
          }
        }
      },
      "NotificationCreate": {
        "type": "object",
        "required": [
          "organizationId",
          "recipient",
          "template"
        ],
        "additionalProperties": false,
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/OrganizationId"
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug",
            "description": "Defaults to the calling product."
          },
          "recipient": {
            "$ref": "#/components/schemas/Recipient"
          },
          "template": {
            "$ref": "#/components/schemas/TemplateKey"
          },
          "channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Channel"
            },
            "uniqueItems": true,
            "minItems": 1,
            "description": "Default: the template's channels."
          },
          "category": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]*$",
            "maxLength": 60,
            "description": "Preference category; default `transactional`."
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Template variables."
          },
          "priority": {
            "type": "string",
            "enum": [
              "high",
              "normal",
              "low"
            ],
            "default": "normal",
            "description": "`high` ignores quiet hours (e.g. security codes)."
          },
          "sendAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Delivery": {
        "type": "object",
        "required": [
          "id",
          "channel",
          "status",
          "attempts",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/DeliveryId"
          },
          "channel": {
            "$ref": "#/components/schemas/Channel"
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "to": {
            "type": "string",
            "description": "Masked address."
          },
          "status": {
            "$ref": "#/components/schemas/DeliveryStatus"
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "providerMessageId": {
            "type": [
              "string",
              "null"
            ]
          },
          "attempts": {
            "type": "integer",
            "minimum": 0
          },
          "nextAttemptAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Notification": {
        "type": "object",
        "required": [
          "id",
          "organizationId",
          "productId",
          "template",
          "category",
          "status",
          "deliveries",
          "createdAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/NotificationId"
          },
          "organizationId": {
            "$ref": "#/components/schemas/OrganizationId"
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "recipientUserId": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UserId"
              },
              {
                "type": "null"
              }
            ]
          },
          "template": {
            "$ref": "#/components/schemas/TemplateKey"
          },
          "category": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/NotificationStatus"
          },
          "deliveries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Delivery"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "NotificationPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Notification"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "NotificationCategory": {
        "type": "object",
        "required": [
          "key",
          "productId",
          "description",
          "channels",
          "required"
        ],
        "properties": {
          "key": {
            "type": "string"
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "description": {
            "type": "string"
          },
          "channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Channel"
            }
          },
          "required": {
            "type": "boolean",
            "description": "Transactional: cannot be opted out of."
          }
        }
      },
      "NotificationCategoryList": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NotificationCategory"
            }
          }
        }
      },
      "QuietHours": {
        "type": "object",
        "required": [
          "start",
          "end",
          "timeZone"
        ],
        "properties": {
          "start": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
          },
          "end": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
          },
          "timeZone": {
            "type": "string",
            "maxLength": 64
          }
        }
      },
      "NotificationPreference": {
        "type": "object",
        "required": [
          "productId",
          "category",
          "channel",
          "enabled"
        ],
        "properties": {
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "category": {
            "type": "string"
          },
          "channel": {
            "$ref": "#/components/schemas/Channel"
          },
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "NotificationPreferences": {
        "type": "object",
        "required": [
          "items",
          "quietHours",
          "version"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NotificationPreference"
            }
          },
          "quietHours": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/QuietHours"
              },
              {
                "type": "null"
              }
            ]
          },
          "version": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "NotificationPreferencesUpdate": {
        "type": "object",
        "required": [
          "items"
        ],
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NotificationPreference"
            },
            "maxItems": 500
          },
          "quietHours": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/QuietHours"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "NotificationTemplate": {
        "type": "object",
        "required": [
          "id",
          "key",
          "productId",
          "channel",
          "locale",
          "body",
          "createdAt",
          "updatedAt",
          "version"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/TemplateId"
          },
          "key": {
            "$ref": "#/components/schemas/TemplateKey"
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "organizationId": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/OrganizationId"
              },
              {
                "type": "null"
              }
            ]
          },
          "channel": {
            "$ref": "#/components/schemas/Channel"
          },
          "locale": {
            "$ref": "#/components/schemas/Locale"
          },
          "category": {
            "type": "string"
          },
          "subject": {
            "type": [
              "string",
              "null"
            ],
            "description": "E-mail only (Scriban)."
          },
          "body": {
            "type": "string",
            "description": "E-mail: MJML with Scriban placeholders; SMS: Scriban text."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "NotificationTemplatePage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NotificationTemplate"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "NotificationTemplateCreate": {
        "type": "object",
        "required": [
          "key",
          "productId",
          "channel",
          "locale",
          "body"
        ],
        "additionalProperties": false,
        "properties": {
          "key": {
            "$ref": "#/components/schemas/TemplateKey"
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "organizationId": {
            "$ref": "#/components/schemas/OrganizationId"
          },
          "channel": {
            "$ref": "#/components/schemas/Channel"
          },
          "locale": {
            "$ref": "#/components/schemas/Locale"
          },
          "category": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]*$"
          },
          "subject": {
            "type": "string",
            "maxLength": 500
          },
          "body": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200000
          }
        }
      },
      "NotificationTemplateUpdate": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "category": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]*$"
          },
          "subject": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500
          },
          "body": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200000
          }
        }
      },
      "TemplatePreviewRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "data": {
            "type": "object",
            "additionalProperties": true
          },
          "organizationId": {
            "$ref": "#/components/schemas/OrganizationId"
          }
        }
      },
      "TemplatePreview": {
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/Channel"
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "html": {
            "type": [
              "string",
              "null"
            ]
          },
          "text": {
            "type": "string"
          }
        }
      },
      "UnsubscribeResult": {
        "type": "object",
        "required": [
          "category",
          "channel"
        ],
        "properties": {
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "category": {
            "type": "string"
          },
          "channel": {
            "$ref": "#/components/schemas/Channel"
          }
        }
      },
      "EventTypeName": {
        "type": "string",
        "maxLength": 100,
        "pattern": "^[a-z][a-z0-9_-]*(\\.[a-z][a-z0-9_-]*)+$",
        "examples": [
          "backbone.member.added",
          "notes-demo.note.created",
          "conversation.analyzed"
        ],
        "description": "`<namespace>.<entity>.<verb>` (the fact type without `.fact`) or a product's alias for one (`conversation.analyzed`)."
      },
      "EventType": {
        "type": "object",
        "required": [
          "type",
          "namespace",
          "description",
          "version"
        ],
        "properties": {
          "type": {
            "$ref": "#/components/schemas/EventTypeName"
          },
          "namespace": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "schemaUrl": {
            "type": "string"
          },
          "aliasOf": {
            "$ref": "#/components/schemas/EventTypeName",
            "description": "Set for an alias; deliveries to endpoints subscribed with the alias carry the alias as `type`."
          }
        }
      },
      "EventTypeList": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventType"
            }
          }
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "required": [
          "id",
          "url",
          "eventTypes",
          "enabled",
          "createdAt",
          "updatedAt",
          "version"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/WebhookEndpointId"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "eventTypes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventTypeName"
            },
            "description": "Empty = all."
          },
          "enabled": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "previousSecretExpiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Set during the 24 h after a rotation, while the previous secret still signs too (a second signature)."
          }
        }
      },
      "WebhookEndpointWithSecret": {
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookEndpoint"
          },
          {
            "type": "object",
            "required": [
              "secret"
            ],
            "properties": {
              "secret": {
                "type": "string",
                "pattern": "^whsec_[A-Za-z0-9+/=]+$"
              }
            }
          }
        ]
      },
      "WebhookEndpointPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEndpoint"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "WebhookEndpointCreate": {
        "type": "object",
        "required": [
          "url"
        ],
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "description": {
            "type": "string",
            "maxLength": 200
          },
          "eventTypes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventTypeName"
            },
            "uniqueItems": true
          },
          "enabled": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "WebhookEndpointUpdate": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200
          },
          "eventTypes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventTypeName"
            },
            "uniqueItems": true
          },
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "WebhookDeliveryStatus": {
        "type": "string",
        "enum": [
          "pending",
          "succeeded",
          "failed"
        ]
      },
      "WebhookDelivery": {
        "type": "object",
        "required": [
          "id",
          "endpointId",
          "eventType",
          "eventId",
          "status",
          "attempts",
          "createdAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/WebhookMessageId"
          },
          "endpointId": {
            "$ref": "#/components/schemas/WebhookEndpointId"
          },
          "eventType": {
            "$ref": "#/components/schemas/EventTypeName"
          },
          "eventId": {
            "$ref": "#/components/schemas/EventId"
          },
          "status": {
            "$ref": "#/components/schemas/WebhookDeliveryStatus"
          },
          "attempts": {
            "type": "integer",
            "minimum": 0
          },
          "lastAttemptAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "nextAttemptAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "responseStatus": {
            "type": [
              "integer",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "deliveredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastError": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the last attempt failed (timeout, connection error, blocked private address); `null` when it got a response."
          },
          "attemptLog": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookDeliveryAttempt"
            },
            "description": "The last 20 attempts, oldest first."
          }
        }
      },
      "WebhookDeliveryAttempt": {
        "type": "object",
        "required": [
          "attemptedAt",
          "durationMs"
        ],
        "properties": {
          "attemptedAt": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": [
              "integer",
              "null"
            ]
          },
          "durationMs": {
            "type": "integer",
            "minimum": 0
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "WebhookDeliveryDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookDelivery"
          },
          {
            "type": "object",
            "required": [
              "payload"
            ],
            "properties": {
              "payload": {
                "type": "object",
                "description": "The body as sent (`type`, `timestamp`, `data`)."
              },
              "responseBody": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The first 1000 characters of the receiver's last response."
              }
            }
          }
        ]
      },
      "WebhookTestRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "eventType": {
            "$ref": "#/components/schemas/EventTypeName"
          }
        }
      },
      "WebhookDeliveryPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookDelivery"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "AuditEvent": {
        "type": "object",
        "required": [
          "id",
          "organizationId",
          "occurredAt",
          "actor",
          "action",
          "resourceType",
          "resourceId"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/AuditEventId"
          },
          "organizationId": {
            "$ref": "#/components/schemas/OrganizationId"
          },
          "productId": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ProductSlug"
              },
              {
                "type": "null"
              }
            ]
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "actor": {
            "$ref": "#/components/schemas/Actor"
          },
          "action": {
            "type": "string",
            "examples": [
              "backbone.member.added",
              "notes-demo.note.deleted"
            ]
          },
          "resourceType": {
            "type": "string"
          },
          "resourceId": {
            "type": "string"
          },
          "traceId": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "AuditEventPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "AuditEventCreate": {
        "type": "object",
        "required": [
          "id",
          "organizationId",
          "occurredAt",
          "actor",
          "action",
          "resourceType",
          "resourceId"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Producer's id (deduplication)."
          },
          "organizationId": {
            "$ref": "#/components/schemas/OrganizationId"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "actor": {
            "$ref": "#/components/schemas/Actor"
          },
          "action": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$",
            "maxLength": 120
          },
          "resourceType": {
            "type": "string",
            "maxLength": 60
          },
          "resourceId": {
            "type": "string",
            "maxLength": 64
          },
          "traceId": {
            "type": "string",
            "maxLength": 64
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "Meter": {
        "type": "object",
        "required": [
          "key",
          "unit",
          "description"
        ],
        "properties": {
          "key": {
            "$ref": "#/components/schemas/MeterKey"
          },
          "unit": {
            "type": "string",
            "examples": [
              "count",
              "bytes",
              "seconds"
            ]
          },
          "description": {
            "type": "string"
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          }
        }
      },
      "MeterList": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Meter"
            }
          }
        }
      },
      "UsageRecord": {
        "type": "object",
        "required": [
          "id",
          "organizationId",
          "meter",
          "quantity",
          "occurredAt"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Producer's id (deduplication)."
          },
          "organizationId": {
            "$ref": "#/components/schemas/OrganizationId"
          },
          "meter": {
            "$ref": "#/components/schemas/MeterKey"
          },
          "quantity": {
            "type": "number"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "livemode": {
            "type": "boolean",
            "default": true
          },
          "dimensions": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "maxProperties": 10
          },
          "resourceId": {
            "$ref": "#/components/schemas/ResourceId",
            "description": "The product resource the usage belongs to (per-resource budgets); defaults to the `resourceId` dimension."
          }
        }
      },
      "UsageRecordBatch": {
        "type": "object",
        "required": [
          "records"
        ],
        "properties": {
          "records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageRecord"
            },
            "minItems": 1,
            "maxItems": 500
          }
        },
        "additionalProperties": false
      },
      "UsageRecordBatchResult": {
        "type": "object",
        "required": [
          "accepted",
          "duplicates"
        ],
        "properties": {
          "accepted": {
            "type": "integer"
          },
          "duplicates": {
            "type": "integer"
          }
        }
      },
      "UsageBucket": {
        "type": "object",
        "required": [
          "meter",
          "startsAt",
          "endsAt",
          "quantity",
          "livemode"
        ],
        "properties": {
          "meter": {
            "$ref": "#/components/schemas/MeterKey"
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "startsAt": {
            "type": "string",
            "format": "date-time"
          },
          "endsAt": {
            "type": "string",
            "format": "date-time"
          },
          "quantity": {
            "type": "number"
          },
          "livemode": {
            "type": "boolean"
          }
        }
      },
      "UsageReport": {
        "type": "object",
        "required": [
          "granularity",
          "items"
        ],
        "properties": {
          "granularity": {
            "type": "string",
            "enum": [
              "hour",
              "day",
              "month"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageBucket"
            }
          }
        }
      },
      "BudgetState": {
        "type": "string",
        "enum": [
          "ok",
          "warning",
          "exceeded"
        ]
      },
      "BudgetStatus": {
        "type": "object",
        "required": [
          "id",
          "source",
          "productId",
          "meter",
          "monthlyLimit",
          "warnPercent",
          "hardStop",
          "period",
          "periodStartsAt",
          "periodEndsAt",
          "used",
          "percent",
          "state"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "A budget id, or `plan:<meter>` for a plan limit."
          },
          "source": {
            "type": "string",
            "enum": [
              "budget",
              "plan"
            ]
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "meter": {
            "$ref": "#/components/schemas/MeterKey"
          },
          "resourceId": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "monthlyLimit": {
            "type": "number"
          },
          "warnPercent": {
            "type": "integer"
          },
          "hardStop": {
            "type": "boolean"
          },
          "includeTestMode": {
            "type": "boolean"
          },
          "timeZone": {
            "type": "string"
          },
          "period": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}$",
            "examples": [
              "2026-10"
            ]
          },
          "periodStartsAt": {
            "type": "string",
            "format": "date-time"
          },
          "periodEndsAt": {
            "type": "string",
            "format": "date-time"
          },
          "used": {
            "type": "number",
            "description": "This period's usage of the meter (in the meter's unit)."
          },
          "percent": {
            "type": "number"
          },
          "state": {
            "$ref": "#/components/schemas/BudgetState"
          }
        }
      },
      "Budget": {
        "type": "object",
        "required": [
          "id",
          "productId",
          "meter",
          "monthlyLimit",
          "warnPercent",
          "hardStop",
          "includeTestMode",
          "timeZone",
          "period",
          "periodStartsAt",
          "periodEndsAt",
          "used",
          "percent",
          "state",
          "createdAt",
          "updatedAt",
          "version"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/BudgetId"
          },
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "meter": {
            "$ref": "#/components/schemas/MeterKey"
          },
          "resourceId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Only usage of this resource counts; `null` = the whole organization."
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "monthlyLimit": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "In the meter's unit (e.g. USD for a cost meter)."
          },
          "warnPercent": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "hardStop": {
            "type": "boolean",
            "description": "Products refuse new billable work while the limit is reached (`402 budget_exceeded`)."
          },
          "includeTestMode": {
            "type": "boolean",
            "description": "Count test-mode usage too."
          },
          "timeZone": {
            "type": "string",
            "description": "IANA time zone of the calendar month."
          },
          "period": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}$"
          },
          "periodStartsAt": {
            "type": "string",
            "format": "date-time"
          },
          "periodEndsAt": {
            "type": "string",
            "format": "date-time"
          },
          "used": {
            "type": "number"
          },
          "percent": {
            "type": "number"
          },
          "state": {
            "$ref": "#/components/schemas/BudgetState"
          },
          "createdBy": {
            "$ref": "#/components/schemas/Actor"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "BudgetPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Budget"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "BudgetCreate": {
        "type": "object",
        "required": [
          "productId",
          "meter",
          "monthlyLimit"
        ],
        "additionalProperties": false,
        "properties": {
          "productId": {
            "$ref": "#/components/schemas/ProductSlug"
          },
          "meter": {
            "$ref": "#/components/schemas/MeterKey"
          },
          "resourceId": {
            "$ref": "#/components/schemas/ResourceId"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "monthlyLimit": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000000000000
          },
          "warnPercent": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 80
          },
          "hardStop": {
            "type": "boolean",
            "default": false
          },
          "includeTestMode": {
            "type": "boolean",
            "default": true
          },
          "timeZone": {
            "type": "string",
            "default": "UTC",
            "examples": [
              "Europe/Amsterdam"
            ]
          }
        }
      },
      "BudgetUpdate": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 80
          },
          "monthlyLimit": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000000000000
          },
          "warnPercent": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "hardStop": {
            "type": "boolean"
          },
          "includeTestMode": {
            "type": "boolean"
          },
          "timeZone": {
            "type": "string"
          }
        }
      },
      "BudgetCheck": {
        "type": "object",
        "required": [
          "allowed",
          "items",
          "blocking"
        ],
        "properties": {
          "allowed": {
            "type": "boolean",
            "description": "False = refuse new billable work with `402 budget_exceeded`."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BudgetStatus"
            }
          },
          "blocking": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BudgetStatus"
            },
            "description": "The used-up hard-stop budgets and plan limits."
          }
        }
      },
      "FeatureFlagRule": {
        "type": "object",
        "required": [],
        "properties": {
          "organizationIds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrganizationId"
            }
          },
          "plans": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "percentage": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "enabled": {
            "type": "boolean"
          },
          "variant": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "FeatureFlag": {
        "type": "object",
        "required": [
          "key",
          "description",
          "enabled",
          "rules",
          "updatedAt",
          "version"
        ],
        "properties": {
          "key": {
            "$ref": "#/components/schemas/FlagKey"
          },
          "productId": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ProductSlug"
              },
              {
                "type": "null"
              }
            ]
          },
          "description": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "variant": {
            "type": [
              "string",
              "null"
            ]
          },
          "rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeatureFlagRule"
            }
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "FeatureFlagPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeatureFlag"
            }
          },
          "nextCursor": {
            "$ref": "#/components/schemas/Cursor"
          }
        }
      },
      "FeatureFlagUpsert": {
        "type": "object",
        "required": [
          "description",
          "enabled"
        ],
        "additionalProperties": false,
        "properties": {
          "productId": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ProductSlug"
              },
              {
                "type": "null"
              }
            ]
          },
          "description": {
            "type": "string",
            "maxLength": 300
          },
          "enabled": {
            "type": "boolean"
          },
          "variant": {
            "type": [
              "string",
              "null"
            ]
          },
          "rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeatureFlagRule"
            },
            "maxItems": 50
          }
        }
      },
      "FeatureFlagEvaluation": {
        "type": "object",
        "required": [
          "key",
          "enabled"
        ],
        "properties": {
          "key": {
            "$ref": "#/components/schemas/FlagKey"
          },
          "enabled": {
            "type": "boolean"
          },
          "variant": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "FeatureFlagEvaluationList": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeatureFlagEvaluation"
            }
          }
        }
      },
      "webhook-envelope": {
        "title": "Webhook payload (Standard Webhooks)",
        "type": "object",
        "required": [
          "type",
          "timestamp",
          "data"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "`<namespace>.<entity>.<verb>` (the fact type without `.fact`)."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          }
        }
      },
      "organizationId": {
        "type": "string",
        "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "organization": {
        "type": "object",
        "required": [
          "id",
          "name",
          "slug"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "defaultLocale": {
            "type": "string"
          },
          "branding": {
            "type": "object",
            "properties": {
              "primaryColor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "logoUrl": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "displayName": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "accentColor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "logoDarkUrl": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "faviconUrl": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "emailSenderName": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "supportUrl": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "websiteUrl": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "hidePoweredBy": {
                "type": [
                  "boolean",
                  "null"
                ]
              }
            }
          }
        }
      },
      "actor": {
        "type": "object",
        "required": [
          "type",
          "id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "user",
              "apiKey",
              "service",
              "system"
            ]
          },
          "id": {
            "type": "string"
          }
        }
      },
      "backbone.organization.created.v1": {
        "title": "backbone.fact.organization.created (v1)",
        "description": "An organization was created. `data` of the fact `backbone.fact.organization.created` and of the webhook `backbone.organization.created`.",
        "type": "object",
        "required": [
          "organizationId",
          "organization"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "organization": {
            "$ref": "#/components/schemas/organization"
          },
          "createdBy": {
            "$ref": "#/components/schemas/actor"
          }
        },
        "additionalProperties": true
      },
      "backbone.organization.updated.v1": {
        "title": "backbone.fact.organization.updated (v1)",
        "description": "An organization changed (name, branding, locale). `data` of the fact `backbone.fact.organization.updated` and of the webhook `backbone.organization.updated`.",
        "type": "object",
        "required": [
          "organizationId",
          "organization",
          "changedFields"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "organization": {
            "$ref": "#/components/schemas/organization"
          },
          "changedFields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "membership": {
        "type": "object",
        "required": [
          "id",
          "organizationId",
          "userId",
          "role"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^mem_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "organizationId": {
            "type": "string",
            "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "userId": {
            "type": "string",
            "pattern": "^usr_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "member",
              "viewer"
            ]
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "backbone.membership.added.v1": {
        "title": "backbone.fact.membership.added (v1)",
        "description": "Someone became a member (accepted invitation or created the organization). `data` of the fact `backbone.fact.membership.added` and of the webhook `backbone.membership.added`.",
        "type": "object",
        "required": [
          "organizationId",
          "membership"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "membership": {
            "$ref": "#/components/schemas/membership"
          }
        },
        "additionalProperties": true
      },
      "backbone.membership.changed.v1": {
        "title": "backbone.fact.membership.changed (v1)",
        "description": "A member's role changed. `data` of the fact `backbone.fact.membership.changed` and of the webhook `backbone.membership.changed`.",
        "type": "object",
        "required": [
          "organizationId",
          "membership",
          "previousRole"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "membership": {
            "$ref": "#/components/schemas/membership"
          },
          "previousRole": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "backbone.membership.removed.v1": {
        "title": "backbone.fact.membership.removed (v1)",
        "description": "A member left or was removed. `data` of the fact `backbone.fact.membership.removed` and of the webhook `backbone.membership.removed`.",
        "type": "object",
        "required": [
          "organizationId",
          "membershipId",
          "userId"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "membershipId": {
            "type": "string",
            "pattern": "^mem_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "userId": {
            "type": "string",
            "pattern": "^usr_[0-9A-HJKMNP-TV-Z]{26}$"
          }
        },
        "additionalProperties": true
      },
      "backbone.invitation.created.v1": {
        "title": "backbone.fact.invitation.created (v1)",
        "description": "Someone was invited. `data` of the fact `backbone.fact.invitation.created` and of the webhook `backbone.invitation.created`.",
        "type": "object",
        "required": [
          "organizationId",
          "invitationId",
          "email",
          "role"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "invitationId": {
            "type": "string",
            "pattern": "^inv_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "role": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "apiKey": {
        "type": "object",
        "required": [
          "id",
          "name",
          "mode",
          "prefix",
          "scopes"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^key_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "name": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ]
          },
          "prefix": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "productIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "kind": {
            "type": "string",
            "enum": [
              "secret",
              "publishable"
            ]
          },
          "productId": {
            "type": [
              "string",
              "null"
            ],
            "description": "The product whose key namespace (prefix) the key was issued in; null = a backbone key."
          },
          "resourceIds": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "allowedOrigins": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "rateLimitPerMinute": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          }
        }
      },
      "backbone.api-key.created.v1": {
        "title": "backbone.fact.api-key.created (v1)",
        "description": "An API key was created. `data` of the fact `backbone.fact.api-key.created` and of the webhook `backbone.api-key.created`.",
        "type": "object",
        "required": [
          "organizationId",
          "apiKey"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "apiKey": {
            "$ref": "#/components/schemas/apiKey"
          }
        },
        "additionalProperties": true
      },
      "backbone.api-key.revoked.v1": {
        "title": "backbone.fact.api-key.revoked (v1)",
        "description": "An API key was revoked; products must drop cached verifications. `data` of the fact `backbone.fact.api-key.revoked` and of the webhook `backbone.api-key.revoked`.",
        "type": "object",
        "required": [
          "organizationId",
          "apiKeyId"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "apiKeyId": {
            "type": "string",
            "pattern": "^key_[0-9A-HJKMNP-TV-Z]{26}$"
          }
        },
        "additionalProperties": true
      },
      "backbone.api-key.updated.v1": {
        "title": "backbone.fact.api-key.updated (v1)",
        "description": "An API key's name, scopes, bindings or rate limit changed (products drop cached verifications). `data` of the fact `backbone.fact.api-key.updated` and of the webhook `backbone.api-key.updated`.",
        "type": "object",
        "required": [
          "organizationId",
          "apiKey",
          "changedFields"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "apiKey": {
            "$ref": "#/components/schemas/apiKey"
          },
          "changedFields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "budget": {
        "type": "object",
        "required": [
          "id",
          "organizationId",
          "productId",
          "meter",
          "monthlyLimit",
          "warnPercent",
          "hardStop",
          "period",
          "used",
          "percent",
          "state"
        ],
        "description": "A monthly budget on one meter of one product and where it stands this period.",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^bud_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "productId": {
            "type": "string"
          },
          "meter": {
            "type": "string"
          },
          "resourceId": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "monthlyLimit": {
            "type": "number"
          },
          "warnPercent": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "hardStop": {
            "type": "boolean"
          },
          "period": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}$"
          },
          "used": {
            "type": "number"
          },
          "percent": {
            "type": "number"
          },
          "state": {
            "type": "string",
            "enum": [
              "ok",
              "warning",
              "exceeded"
            ]
          }
        }
      },
      "backbone.budget.alerted.v1": {
        "title": "backbone.fact.budget.alerted (v1)",
        "description": "A monthly budget reached its warning share (`level` = `warning`) or its limit (`exceeded`) for the first time in its period. `data` of the fact `backbone.fact.budget.alerted` and of the webhook `backbone.budget.alerted`.",
        "type": "object",
        "required": [
          "organizationId",
          "level",
          "budget"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "level": {
            "type": "string",
            "enum": [
              "warning",
              "exceeded"
            ]
          },
          "budget": {
            "$ref": "#/components/schemas/budget"
          }
        },
        "additionalProperties": true
      },
      "delivery": {
        "type": "object",
        "required": [
          "notificationId",
          "deliveryId",
          "channel",
          "status"
        ],
        "properties": {
          "notificationId": {
            "type": "string",
            "pattern": "^ntf_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "deliveryId": {
            "type": "string",
            "pattern": "^dlv_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "sms"
            ]
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "productId": {
            "type": "string"
          },
          "template": {
            "type": "string"
          },
          "recipientUserId": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "backbone.notification.delivered.v1": {
        "title": "backbone.fact.notification.delivered (v1)",
        "description": "The provider confirmed delivery (or acceptance, for providers without receipts). `data` of the fact `backbone.fact.notification.delivered` and of the webhook `backbone.notification.delivered`.",
        "type": "object",
        "required": [
          "organizationId",
          "delivery"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "delivery": {
            "$ref": "#/components/schemas/delivery"
          }
        },
        "additionalProperties": true
      },
      "backbone.notification.bounced.v1": {
        "title": "backbone.fact.notification.bounced (v1)",
        "description": "The address bounced or was rejected permanently. `data` of the fact `backbone.fact.notification.bounced` and of the webhook `backbone.notification.bounced`.",
        "type": "object",
        "required": [
          "organizationId",
          "delivery"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "delivery": {
            "$ref": "#/components/schemas/delivery"
          }
        },
        "additionalProperties": true
      },
      "backbone.notification.failed.v1": {
        "title": "backbone.fact.notification.failed (v1)",
        "description": "Delivery failed after all retries and fallbacks. `data` of the fact `backbone.fact.notification.failed` and of the webhook `backbone.notification.failed`.",
        "type": "object",
        "required": [
          "organizationId",
          "delivery"
        ],
        "properties": {
          "organizationId": {
            "$ref": "#/components/schemas/organizationId"
          },
          "delivery": {
            "$ref": "#/components/schemas/delivery"
          }
        },
        "additionalProperties": true
      }
    }
  }
}