openapi: 3.1.0
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
info:
  title: ProudAuth API
  version: 1.0.0
  summary: 'Self-hosted identity provider: protocol, interaction, self-service, tenant and administration APIs.'
  description: >
    Contract for the ProudAuth custom HTTP API (`/api/v1/realms/{realm}/...`) and the protocol endpoints served under
    the path-based issuer (`/realms/{realm}`). Generated from the server code (internal/httpapi) and kept in sync by
    tests/contract.


    Conventions (docs/plan.md section 25):


    * **Errors.** Custom APIs return RFC 9457 problem details (`application/problem+json`, schema `Problem`) with a
    stable `code` and the `request_id`. OAuth/OIDC endpoints return standard OAuth errors (`OAuthError`).

    * **Strict JSON.** Request bodies must be `application/json`, are size-bounded, and are rejected when they contain
    duplicate or unknown members (`additionalProperties: false`).

    * **Authentication.** Bearer tokens only in the `Authorization` header (never query strings). 401 for
    missing/invalid credentials, 403 for authenticated-but-disallowed, 404 where existence is concealed.

    * **Idempotency.** Every authenticated POST accepts `Idempotency-Key` (24 hours, actor/realm/route-bound, matched on
    the exact path and body). Only successful responses are recorded, and responses that carried one-time secrets are
    never replayed.

    * **One-time secrets.** Fields marked `x-secret: true` (client secrets, API keys, personal tokens, setup tokens,
    recovery codes, signing secrets, handoff codes, download tokens, continuation tokens) are returned exactly once.

    * **Concurrency.** Editable resources return a weak `ETag` (`W/"v{version}"`); send it in `If-Match`. Stale versions
    return 412; where `If-Match` is required, omitting it returns 428.

    * **Pagination.** Cursor-paginated lists accept `cursor` and `limit` and return `next_cursor` (empty string on the
    last page).

    * **Correlation.** `X-Request-Id` is accepted (printable ASCII, at most 64 characters) or generated, and echoed on
    every response.

    * **Throttling.** 429 and 503 responses include `Retry-After`.

    * **Trust classes and permissions.** `x-trust-class` records the section 25.2 trust class of each operation;
    `x-permissions` lists the permissions the server checks (any one suffices unless noted). Organization-scoped `org.*`
    permissions are evaluated in the organization named by the path, whose existence is concealed (404) from callers
    without any permission in it.
  license:
    name: See LICENSE
    url: https://proudauth.com/docs/reference/license/
servers:
  - url: '{origin}'
    description: The configured public origin (server.public_origin).
    variables:
      origin:
        default: https://identity.example.com
tags:
  - name: Extensions
    description: Lifecycle workflows, signed plugins and extension contract versions (EXT-013..EXT-018).
  - name: Registry
    description: Container-registry token bridge (ADV-010).
  - name: Passkeys
    description: Passkey attestation trust and WebAuthn Level 3 related origins (PASS-009, PASS-010).
  - name: SAML
    description: SAML 2.0 identity provider (SAML applications) and broker (SAML connections), their metadata and signing keys.
  - name: Authentication flows
    description: 'Versioned authentication-flow definitions: analysis, simulation, publication and rollback (AUT-019).'
  - name: Shared signals
    description: 'Shared Signals Framework transmitter: CAEP and RISC security events by push or poll (AUD-016).'
  - name: Directory
    description: >-
      LDAP/Active Directory federation and synchronization, outbound SCIM provisioning, reconciliation and connector
      evidence (PROV-010..PROV-014, PROV-017, PROV-018, FED-015, USR-022).
  - name: Discovery
    description: 'Public metadata: OpenID configuration, RFC 8414 metadata and JWKS.'
  - name: OAuth
    description: >-
      OAuth 2.0 protocol endpoints (authorize, token, introspect, revoke, device authorization, PAR). Errors use the
      OAuth JSON format, not problem details.
  - name: OIDC
    description: OpenID Connect UserInfo and RP-initiated logout.
  - name: CORS
    description: CORS preflight for registered client origins.
  - name: Interaction
    description: Headless authentication transactions, registration, password reset and account setup.
  - name: Self-service
    description: The calling user's own profile, identifiers, credentials, sessions, consents and tokens (/me).
  - name: Organizations
    description: Tenant (organization) lifecycle, members, roles, join requests, groups and domains.
  - name: Invitations
    description: Organization invitations.
  - name: Users
    description: User administration.
  - name: Projects
    description: Project administration.
  - name: Clients
    description: OAuth client registration and credentials.
  - name: Resources
    description: Protected APIs (resources), scopes and introspectors.
  - name: Authorization
    description: Permissions, roles, role assignments and the policy decision API.
  - name: Machine identities
    description: Service principals, API keys and credential inventory.
  - name: Realm
    description: Realm policy, emergency state and signing keys.
  - name: Audit
    description: Audit evidence queries, integrity and exports.
  - name: Jobs
    description: Asynchronous jobs and protected result downloads.
  - name: Provisioning
    description: Inbound SCIM 2.0 provisioning and connector management (PROV-001..PROV-009, PROV-018).
  - name: Federation
    description: Upstream identity providers (OIDC and social), federated sign-in callbacks and linked identities.
  - name: Support access
    description: Support impersonation requests, grants and handoffs.
  - name: Webhooks
    description: Webhook subscriptions and deliveries (event schemas in api/events).
  - name: Imports and exports
    description: Bulk user import.
  - name: Configuration
    description: Configuration-as-code validation, import and export.
  - name: Notifications
    description: Notification delivery settings, templates and jobs.
  - name: Development
    description: Development-mode only helpers.
  - name: Health
    description: Liveness and readiness probes.
paths:
  /realms/{realm}/.well-known/openid-configuration:
    get:
      operationId: getOpenIDConfiguration
      tags:
        - Discovery
      summary: OpenID Provider metadata
      description: Canonical issuer metadata for the realm. Cacheable for 300 seconds.
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Cache-Control:
              schema:
                type: string
              description: public, max-age=300
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIDConfiguration'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /.well-known/oauth-authorization-server/realms/{realm}:
    get:
      operationId: getOAuthServerMetadata
      tags:
        - Discovery
      summary: OAuth 2.0 authorization server metadata (RFC 8414)
      description: RFC 8414 location for the path-based issuer; same document as the OpenID configuration.
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Cache-Control:
              schema:
                type: string
              description: public, max-age=300
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIDConfiguration'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/jwks:
    get:
      operationId: getJWKS
      tags:
        - Discovery
      summary: Public verification keys
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Cache-Control:
              schema:
                type: string
              description: public, max-age=300
          content:
            application/jwk-set+json:
              schema:
                $ref: '#/components/schemas/JWKSet'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/oauth/authorize:
    get:
      operationId: authorizeGet
      tags:
        - OAuth
      summary: Authorization request (query)
      description: >-
        Starts an authorization-code flow (PKCE S256 required). On success redirects (302) to the login UI or back to
        the client with code, state and iss. Errors that cannot be safely redirected are returned as OAuth JSON errors
        with status 400. May set pa_tx and pa_sid cookies.
      security: []
      x-trust-class: public-protocol-initiation
      x-optional-security:
        - sessionCookie
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: response_type
          in: query
          required: false
          schema:
            type: string
            const: code
          description: response_type
        - name: client_id
          in: query
          required: false
          schema:
            type: string
          description: client_id
        - name: redirect_uri
          in: query
          required: false
          schema:
            type: string
            format: uri
          description: redirect_uri
        - name: scope
          in: query
          required: false
          schema:
            type: string
            maxLength: 2048
          description: scope
        - name: state
          in: query
          required: false
          schema:
            type: string
            maxLength: 1024
          description: state
        - name: nonce
          in: query
          required: false
          schema:
            type: string
            maxLength: 512
          description: nonce
        - name: code_challenge
          in: query
          required: false
          schema:
            type: string
          description: code_challenge
        - name: code_challenge_method
          in: query
          required: false
          schema:
            type: string
            const: S256
          description: code_challenge_method
        - name: response_mode
          in: query
          required: false
          schema:
            type: string
            enum:
              - query
              - query.jwt
              - jwt
          description: >-
            query (default), or query.jwt / jwt (the same for the code flow) for a JWT-secured authorization response
            (JARM, ADV-002): the redirect carries one parameter, response, a JWT signed by the realm (iss,
            aud=client_id, exp, code or error, state) and encrypted to the client when it registered
            authorization_encrypted_response_alg. Errors returned to the redirect use the same mode.
        - name: prompt
          in: query
          required: false
          schema:
            type: string
          description: prompt
        - name: max_age
          in: query
          required: false
          schema:
            type: string
          description: max_age
        - name: acr_values
          in: query
          required: false
          schema:
            type: string
          description: acr_values
        - name: login_hint
          in: query
          required: false
          schema:
            type: string
            maxLength: 512
          description: login_hint
        - name: ui_locales
          in: query
          required: false
          schema:
            type: string
          description: ui_locales
        - name: organization
          in: query
          required: false
          schema:
            type: string
            description: Organization hint (ID or slug).
          description: Organization hint (ID or slug).
        - name: resource
          in: query
          required: false
          schema:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
                maxItems: 5
            description: RFC 8707 resource indicator; may repeat (at most 5).
          description: RFC 8707 resource indicator; may repeat (at most 5).
        - name: request_uri
          in: query
          required: false
          schema:
            type: string
            description: PAR request_uri (urn:ietf:params:oauth:request_uri:...).
          description: PAR request_uri (urn:ietf:params:oauth:request_uri:...).
        - name: request
          in: query
          required: false
          schema:
            type: string
            description: Request objects are not supported (request_parameter_supported=false).
          description: Request objects are not supported (request_parameter_supported=false).
        - name: claims
          in: query
          required: false
          schema:
            type: string
            description: The claims parameter is not supported.
          description: The claims parameter is not supported.
        - name: intent
          in: query
          required: false
          schema:
            type: string
            description: Interaction intent hint, e.g. login or register.
          description: Interaction intent hint, e.g. login or register.
      responses:
        '302':
          description: Found (redirect)
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '400':
          $ref: '#/components/responses/OAuthError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: authorizePost
      tags:
        - OAuth
      summary: Authorization request (form post)
      description: >-
        Starts an authorization-code flow (PKCE S256 required). On success redirects (302) to the login UI or back to
        the client with code, state and iss. Errors that cannot be safely redirected are returned as OAuth JSON errors
        with status 400. May set pa_tx and pa_sid cookies.
      security: []
      x-trust-class: public-protocol-initiation
      x-optional-security:
        - sessionCookie
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                response_type:
                  type: string
                  const: code
                client_id:
                  type: string
                redirect_uri:
                  type: string
                  format: uri
                scope:
                  type: string
                  maxLength: 2048
                state:
                  type: string
                  maxLength: 1024
                nonce:
                  type: string
                  maxLength: 512
                code_challenge:
                  type: string
                code_challenge_method:
                  type: string
                  const: S256
                response_mode:
                  type: string
                  enum:
                    - query
                    - query.jwt
                    - jwt
                prompt:
                  type: string
                max_age:
                  type: string
                acr_values:
                  type: string
                login_hint:
                  type: string
                  maxLength: 512
                ui_locales:
                  type: string
                organization:
                  type: string
                  description: Organization hint (ID or slug).
                resource:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                      maxItems: 5
                  description: RFC 8707 resource indicator; may repeat (at most 5).
                request_uri:
                  type: string
                  description: PAR request_uri (urn:ietf:params:oauth:request_uri:...).
                request:
                  type: string
                  description: Request objects are not supported (request_parameter_supported=false).
                claims:
                  type: string
                  description: The claims parameter is not supported.
                intent:
                  type: string
                  description: Interaction intent hint, e.g. login or register.
              additionalProperties: false
      responses:
        '302':
          description: Found (redirect)
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '400':
          $ref: '#/components/responses/OAuthError'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/oauth/token:
    post:
      operationId: token
      tags:
        - OAuth
      summary: Token endpoint
      description: >-
        Issues tokens for the enabled grants. Parameters must be form-encoded in the body (query parameters are
        rejected) and must not repeat (except resource). Optional DPoP proof in the DPoP header. When issuance fails for
        a configuration reason (the client registered response encryption but has no key that can receive it: 400
        unauthorized_client; no active signing key: 503 temporarily_unavailable), the issuance is rolled back and the
        code, device code or refresh token is not consumed, so a retry is not treated as replay.
      security:
        - clientSecretBasic: []
        - {}
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: DPoP
          in: header
          required: false
          schema:
            type: string
          description: DPoP proof JWT (RFC 9449).
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: Client identifier (client_secret_post, private_key_jwt or public clients).
                client_secret:
                  type: string
                  format: password
                  description: client_secret_post credential. Prefer client_secret_basic.
                client_assertion_type:
                  type: string
                  const: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                client_assertion:
                  type: string
                  description: private_key_jwt assertion (audience is the endpoint URL).
                grant_type:
                  type: string
                  enum:
                    - authorization_code
                    - refresh_token
                    - client_credentials
                    - urn:ietf:params:oauth:grant-type:device_code
                    - urn:ietf:params:oauth:grant-type:token-exchange
                    - urn:ietf:params:oauth:grant-type:jwt-bearer
                  description: >-
                    Grants the token endpoint implements; others return unsupported_grant_type. jwt-bearer (RFC 7523) is
                    workload federation (MCH-011, ADV-004): assertion is a workload token from an issuer the client
                    trusts (see /clients/{client}/workload-trusts), and the token issued represents the client's service
                    principal and never outlives the assertion. It is distinct from client authentication with
                    client_assertion. The assertion's jti is spent only when the token is issued (in the issuing
                    transaction), so a request refused for its resource, organization or scope leaves the assertion
                    usable. A refused assertion returns invalid_grant without the reason (the reason is audited as
                    workload.assertion.rejected).
                code:
                  type: string
                  x-secret: true
                redirect_uri:
                  type: string
                code_verifier:
                  type: string
                refresh_token:
                  type: string
                  x-secret: true
                  description: Refresh tokens rotate on use; reuse revokes the family.
                scope:
                  type: string
                resource:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                organization:
                  type: string
                device_code:
                  type: string
                  x-secret: true
                assertion:
                  type: string
                  x-secret: true
                  description: The workload assertion for the jwt-bearer grant.
                subject_token:
                  type: string
                  x-secret: true
                subject_token_type:
                  type: string
                actor_token:
                  type: string
                  x-secret: true
                requested_token_type:
                  type: string
                audience:
                  type: string
              required:
                - grant_type
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/OAuthError'
        '401':
          $ref: '#/components/responses/OAuthError'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/OAuthError'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/oauth/introspect:
    post:
      operationId: introspect
      tags:
        - OAuth
      summary: Token introspection (RFC 7662)
      description: >-
        Only confidential clients registered as introspectors for the token audience see active results. API keys
        (pa_key_) and personal tokens (pa_pat_) are introspected with the same rules.
      security:
        - clientSecretBasic: []
        - {}
      x-trust-class: resource-server
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: Client identifier (client_secret_post, private_key_jwt or public clients).
                client_secret:
                  type: string
                  format: password
                  description: client_secret_post credential. Prefer client_secret_basic.
                client_assertion_type:
                  type: string
                  const: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                client_assertion:
                  type: string
                  description: private_key_jwt assertion (audience is the endpoint URL).
                token:
                  type: string
                  x-secret: true
                token_type_hint:
                  type: string
              required:
                - token
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntrospectionResponse'
        '400':
          $ref: '#/components/responses/OAuthError'
        '401':
          $ref: '#/components/responses/OAuthError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/oauth/revoke:
    post:
      operationId: revoke
      tags:
        - OAuth
      summary: Token revocation (RFC 7009)
      description: Returns 200 with an empty body for valid and unknown tokens alike.
      security:
        - clientSecretBasic: []
        - {}
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: Client identifier (client_secret_post, private_key_jwt or public clients).
                client_secret:
                  type: string
                  format: password
                  description: client_secret_post credential. Prefer client_secret_basic.
                client_assertion_type:
                  type: string
                  const: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                client_assertion:
                  type: string
                  description: private_key_jwt assertion (audience is the endpoint URL).
                token:
                  type: string
                  x-secret: true
                token_type_hint:
                  type: string
                  enum:
                    - access_token
                    - refresh_token
              required:
                - token
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '400':
          $ref: '#/components/responses/OAuthError'
        '401':
          $ref: '#/components/responses/OAuthError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/oauth/device_authorization:
    post:
      operationId: deviceAuthorization
      tags:
        - OAuth
      summary: Device authorization request (RFC 8628)
      security:
        - clientSecretBasic: []
        - {}
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: Client identifier (client_secret_post, private_key_jwt or public clients).
                client_secret:
                  type: string
                  format: password
                  description: client_secret_post credential. Prefer client_secret_basic.
                client_assertion_type:
                  type: string
                  const: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                client_assertion:
                  type: string
                  description: private_key_jwt assertion (audience is the endpoint URL).
                scope:
                  type: string
                resource:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAuthorizationResponse'
        '400':
          $ref: '#/components/responses/OAuthError'
        '401':
          $ref: '#/components/responses/OAuthError'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/OAuthError'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/oauth/par:
    post:
      operationId: pushAuthorizationRequest
      tags:
        - OAuth
      summary: Pushed authorization request (RFC 9126)
      description: >-
        Requires an authenticated client. request_uri is not allowed in a pushed request; the returned request_uri is
        single-use and expires after 60 seconds.
      security:
        - clientSecretBasic: []
        - {}
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
                  format: password
                  description: client_secret_post credential. Prefer client_secret_basic.
                client_assertion_type:
                  type: string
                  const: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                client_assertion:
                  type: string
                  description: private_key_jwt assertion (audience is the endpoint URL).
                response_type:
                  type: string
                  const: code
                redirect_uri:
                  type: string
                  format: uri
                scope:
                  type: string
                  maxLength: 2048
                state:
                  type: string
                  maxLength: 1024
                nonce:
                  type: string
                  maxLength: 512
                code_challenge:
                  type: string
                code_challenge_method:
                  type: string
                  const: S256
                response_mode:
                  type: string
                  enum:
                    - query
                    - query.jwt
                    - jwt
                prompt:
                  type: string
                max_age:
                  type: string
                acr_values:
                  type: string
                login_hint:
                  type: string
                  maxLength: 512
                ui_locales:
                  type: string
                organization:
                  type: string
                  description: Organization hint (ID or slug).
                resource:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                      maxItems: 5
                  description: RFC 8707 resource indicator; may repeat (at most 5).
                request:
                  type: string
                  description: Request objects are not supported (request_parameter_supported=false).
                claims:
                  type: string
                  description: The claims parameter is not supported.
                intent:
                  type: string
                  description: Interaction intent hint, e.g. login or register.
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushedAuthorizationResponse'
        '400':
          $ref: '#/components/responses/OAuthError'
        '401':
          $ref: '#/components/responses/OAuthError'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/oidc/userinfo:
    get:
      operationId: userinfoGet
      tags:
        - OIDC
      summary: UserInfo (GET)
      description: >-
        Returns claims permitted by the access token. Missing or invalid tokens return 401 with an empty body and a
        WWW-Authenticate Bearer challenge.
      security:
        - userAccessToken: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
            application/jwt:
              schema:
                type: string
              description: >-
                OIDC-013: for a client that registered userinfo_signed_response_alg, a JWT signed with the realm key
                whose claims add iss and aud (the client_id); for one that registered userinfo_encrypted_response_alg, a
                JWE encrypted to its newest suitable registered key (nested, cty JWT, when also signed).
        '400':
          description: >-
            The client registered response encryption but has no registered public key that can receive it (error
            invalid_request).
        '401':
          description: Missing or invalid access token (empty body).
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/WWW-Authenticate'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: userinfoPost
      tags:
        - OIDC
      summary: UserInfo (POST)
      description: >-
        Returns claims permitted by the access token. Missing or invalid tokens return 401 with an empty body and a
        WWW-Authenticate Bearer challenge.
      security:
        - userAccessToken: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
            application/jwt:
              schema:
                type: string
              description: >-
                OIDC-013: for a client that registered userinfo_signed_response_alg, a JWT signed with the realm key
                whose claims add iss and aud (the client_id); for one that registered userinfo_encrypted_response_alg, a
                JWE encrypted to its newest suitable registered key (nested, cty JWT, when also signed).
        '400':
          description: >-
            The client registered response encryption but has no registered public key that can receive it (error
            invalid_request).
        '401':
          description: Missing or invalid access token (empty body).
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/WWW-Authenticate'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/oidc/check-session:
    get:
      operationId: checkSessionIframe
      tags:
        - OIDC
      summary: OpenID Connect Session Management check_session_iframe
      description: >-
        OIDC-014, only when the realm policy sets sessions.check_session_iframe (404 otherwise). An HTML page for
        relying parties to embed: it answers postMessage("client_id session_state") with changed, unchanged or error,
        only to an origin registered for the client, recomputing session_state from the pa_opbs browser-state cookie and
        the message origin. Browsers that block or partition third-party cookies make every check report changed;
        server-side session ends (administrator revocation, timeouts) appear only after the browser next reaches the
        provider, so relying parties should also use back-channel logout or token introspection.
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            text/html:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/oidc/check-session/origin:
    get:
      operationId: checkSessionOrigin
      tags:
        - OIDC
      summary: Check-session iframe origin check
      description: >-
        OIDC-014, used by the check_session_iframe page: whether origin is one of the client's allowed origins or the
        origin of one of its redirect URIs. 404 when session management is off.
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: client_id
          in: query
          required: true
          schema:
            type: string
          description: client_id
        - name: origin
          in: query
          required: true
          schema:
            type: string
          description: The origin of the message the iframe received.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - allowed
                properties:
                  allowed:
                    type: boolean
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/oidc/logout:
    get:
      operationId: logoutGet
      tags:
        - OIDC
      summary: RP-initiated logout (GET)
      description: >-
        A GET without id_token_hint never ends the browser session silently (the client must POST). Redirects (302) to a
        registered post_logout_redirect_uri when valid.
      security: []
      x-trust-class: public-protocol-initiation
      x-optional-security:
        - sessionCookie
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: id_token_hint
          in: query
          required: false
          schema:
            type: string
            x-secret: true
          description: id_token_hint
        - name: client_id
          in: query
          required: false
          schema:
            type: string
          description: client_id
        - name: post_logout_redirect_uri
          in: query
          required: false
          schema:
            type: string
            format: uri
          description: post_logout_redirect_uri
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: state
        - name: upstream_logout
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: >-
            Extension (FED-013): also send the browser to the federated provider's logout endpoint when the ended
            session came from one.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_ended:
                    type: boolean
                  frontchannel_logout_uris:
                    type: array
                    items:
                      type: string
                    description: >-
                      Front-channel logout (SES-018), only to callers sending Accept: application/json: the
                      front-channel logout URIs of the clients that took part in the ended session, for the caller to
                      load in iframes before continuing to redirect_to. Delivery is not confirmed.
                  redirect_to:
                    type: string
                    description: With frontchannel_logout_uris, the post-logout destination the caller continues to afterwards.
                  upstream_logout:
                    type: object
                    description: >-
                      What happened to a federated provider's session (FED-013): not_federated, not_requested (only the
                      local session ended; the provider's session may remain active), unsupported (the provider has no
                      logout endpoint) or unavailable. A redirect to the provider is a 302 instead. With
                      post_logout_redirect_uri and upstream_logout=true, the status is also appended to the redirect as
                      upstream_logout.
                    properties:
                      provider:
                        type: string
                      status:
                        type: string
                        enum:
                          - not_federated
                          - not_requested
                          - redirect
                          - unsupported
                          - unavailable
                required:
                  - session_ended
            text/html:
              schema:
                type: string
              description: >-
                When clients that took part in the ended session registered front-channel logout URIs (SES-018), a
                browser receives a page that loads them in iframes (its Content-Security-Policy frames only those
                origins and runs no script) and continues to the post-logout redirect after two seconds.
        '302':
          description: >-
            Redirect to the registered post-logout URI, or with upstream_logout=true to the federated provider's logout
            endpoint, which returns to /oidc/logout/upstream-return.
          headers:
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: logoutPost
      tags:
        - OIDC
      summary: RP-initiated logout (POST)
      security: []
      x-trust-class: public-protocol-initiation
      x-optional-security:
        - sessionCookie
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                id_token_hint:
                  type: string
                  x-secret: true
                upstream_logout:
                  type: string
                  enum:
                    - 'true'
                    - 'false'
                  description: 'Extension (FED-013): also send the browser to the federated provider''s logout endpoint.'
                client_id:
                  type: string
                post_logout_redirect_uri:
                  type: string
                  format: uri
                state:
                  type: string
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_ended:
                    type: boolean
                  frontchannel_logout_uris:
                    type: array
                    items:
                      type: string
                    description: >-
                      Front-channel logout (SES-018), only to callers sending Accept: application/json: the
                      front-channel logout URIs of the clients that took part in the ended session, for the caller to
                      load in iframes before continuing to redirect_to. Delivery is not confirmed.
                  redirect_to:
                    type: string
                    description: With frontchannel_logout_uris, the post-logout destination the caller continues to afterwards.
                  upstream_logout:
                    type: object
                    description: >-
                      What happened to a federated provider's session (FED-013): not_federated, not_requested (only the
                      local session ended; the provider's session may remain active), unsupported (the provider has no
                      logout endpoint) or unavailable. A redirect to the provider is a 302 instead. With
                      post_logout_redirect_uri and upstream_logout=true, the status is also appended to the redirect as
                      upstream_logout.
                    properties:
                      provider:
                        type: string
                      status:
                        type: string
                        enum:
                          - not_federated
                          - not_requested
                          - redirect
                          - unsupported
                          - unavailable
                required:
                  - session_ended
            text/html:
              schema:
                type: string
              description: >-
                When clients that took part in the ended session registered front-channel logout URIs (SES-018), a
                browser receives a page that loads them in iframes (its Content-Security-Policy frames only those
                origins and runs no script) and continues to the post-logout redirect after two seconds.
        '302':
          description: >-
            Redirect to the registered post-logout URI, or with upstream_logout=true to the federated provider's logout
            endpoint, which returns to /oidc/logout/upstream-return.
          headers:
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/oidc/logout/upstream-return:
    get:
      operationId: logoutUpstreamReturn
      tags:
        - OIDC
      summary: Return from a federated provider's logout
      description: >-
        Where a federated provider sends the browser after its own logout (FED-013); register this URI as a post-logout
        redirect at the provider. The sealed state (valid 15 minutes) names the client's post-logout destination,
        reached with upstream_logout=returned appended: the provider's return does not prove its session ended. Without
        a destination the response is JSON. The state is single-use: a state that is malformed, expired or already used
        is refused with 400 ("invalid state", "expired state", "state already used").
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: state
          in: query
          required: true
          schema:
            type: string
          description: Sealed state issued with the upstream logout redirect.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_ended:
                    type: boolean
                  upstream_logout:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                          - returned
        '302':
          description: Redirect to the client's registered post-logout URI.
          headers:
            Location:
              $ref: '#/components/headers/Location'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/:
    options:
      operationId: corsPreflightProtocol
      tags:
        - CORS
      summary: CORS preflight
      description: >-
        Matches every path below this prefix (Go ServeMux subtree pattern). Only origins registered on active clients
        are reflected; credentials are allowed only for /auth/ paths. Always returns 204.
      security: []
      x-trust-class: public-metadata
      x-path-match: prefix
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/:
    options:
      operationId: corsPreflightApi
      tags:
        - CORS
      summary: CORS preflight
      description: >-
        Matches every path below this prefix (Go ServeMux subtree pattern). Only origins registered on active clients
        are reflected; credentials are allowed only for /auth/ paths. Always returns 204.
      security: []
      x-trust-class: public-metadata
      x-path-match: prefix
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions:
    post:
      operationId: startTransaction
      tags:
        - Interaction
      summary: Start a headless authentication transaction
      description: >-
        Validates the client and request like the authorization endpoint and returns continuation authority plus the
        first next actions (AUT-001).
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Authorization request parameters for a headless (API-driven) login surface, or a device user code.
              properties:
                client_id:
                  type: string
                redirect_uri:
                  type: string
                scope:
                  type: string
                state:
                  type: string
                nonce:
                  type: string
                code_challenge:
                  type: string
                code_challenge_method:
                  type: string
                  const: S256
                prompt:
                  type: string
                max_age:
                  type: string
                acr_values:
                  type: string
                login_hint:
                  type: string
                ui_locales:
                  type: string
                organization:
                  type: string
                resource:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                intent:
                  type: string
                  description: e.g. login or register.
                request_uri:
                  type: string
                  description: PAR request_uri.
                device_user_code:
                  type: string
                  description: Starts a device-flow approval transaction instead of an authorization request.
                response_mode:
                  type: string
                  enum:
                    - query
                    - query.jwt
                    - jwt
                  description: >-
                    query (default), or a JWT-secured authorization response (JARM, ADV-002): redirect_to then carries
                    response=<JWT> instead of code, state and iss.
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionStarted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}:
    get:
      operationId: getTransaction
      tags:
        - Interaction
      summary: Get transaction state
      description: Browser callers (cookie) also receive csrf_token.
      security:
        - transactionToken: []
        - transactionCookie: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/identify:
    post:
      operationId: identifyStep
      tags:
        - Interaction
      summary: Submit identifier
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). Enumeration-safe.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                identifier:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/password:
    post:
      operationId: passwordStep
      tags:
        - Interaction
      summary: Submit password
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). Rate-limited.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                identifier:
                  type: string
                password:
                  type: string
                  format: password
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/otp/send:
    post:
      operationId: sendOTPStep
      tags:
        - Interaction
      summary: Send a one-time code
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). Purpose/identifier-bound send budget.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                purpose:
                  type: string
                  enum:
                    - verify_email
                    - verify_contact
                    - login
                    - magic_link
                  description: >-
                    login sends an email code or, for a phone identifier with SMS sign-in enabled, an SMS code;
                    magic_link emails a single-use link to the configured login UI.
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/otp/verify:
    post:
      operationId: verifyOTPStep
      tags:
        - Interaction
      summary: Verify a one-time code
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). Attempt-limited atomic consumption.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/totp:
    post:
      operationId: totpStep
      tags:
        - Interaction
      summary: Verify a TOTP code
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/hotp:
    post:
      operationId: hotpStep
      tags:
        - Interaction
      summary: Verify an HOTP code
      description: >-
        Counter-based code (MFA-013), offered only in realms that list hotp in mfa.allowed_factors. A code within
        mfa.hotp.look_ahead counters of the stored counter is accepted once; the counter moves past it atomically.
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/challenge:
    post:
      operationId: answerFlowChallenge
      tags:
        - Interaction
      summary: Answer an authentication flow challenge
      description: >-
        Transaction-bound step for a challenge next action (AUT-012, SEC-014): the realm authentication_flow asked for a
        challenge. Give exactly one of provider_response (the token the configured challenge provider issued to the
        login interface; verified with the provider, 503 when the provider is unavailable) or code (sent with POST
        .../challenge/send to the account verified email, the accessible alternative). A wrong answer is 400
        invalid_proof and counts toward the transaction failure limit. An enrolled second factor (TOTP or passkey) also
        satisfies the challenge.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider_response:
                  type: string
                  maxLength: 4096
                code:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/challenge/send:
    post:
      operationId: sendFlowChallengeCode
      tags:
        - Interaction
      summary: Email a challenge code
      description: >-
        Transaction-bound step: sends a one-time code for a pending authentication flow challenge to the account
        verified primary email (SEC-014 accessible alternative), when the realm
        authentication_flow.email_code_alternative is not false. Subject to the send budgets; 409 when no challenge is
        pending or no verified email exists.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/totp/enroll:
    post:
      operationId: enrollTOTPStep
      tags:
        - Interaction
      summary: Begin TOTP enrollment (required action)
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). The request body is ignored. The TOTP seed is returned once in one_time.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/totp/activate:
    post:
      operationId: activateTOTPStep
      tags:
        - Interaction
      summary: Activate TOTP enrollment
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). New recovery codes are returned once in one_time.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/recovery-code:
    post:
      operationId: recoveryCodeStep
      tags:
        - Interaction
      summary: Use a recovery code
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). Produces a recovery-restricted session.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/magic-link:
    post:
      operationId: magicLinkStep
      tags:
        - Interaction
      summary: Complete sign-in with a magic link
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). The link secret (delivered only in the URL fragment of the emailed link) must be
        posted back to the same transaction that requested it with otp/send purpose magic_link; a link from another
        transaction is refused and burned (PWDLESS-002, PWDLESS-003).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: The pa_lnk_ secret from the link fragment.
                  x-secret: true
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/webauthn/options:
    post:
      operationId: webauthnOptionsStep
      tags:
        - Interaction
      summary: Begin passkey authentication
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). Returns WebAuthn request options in the webauthn member. The body must be an
        empty JSON object (or empty).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: >-
          Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected. The body may
          be empty (treated as {}), but Content-Type: application/json is still required.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/webauthn/verify:
    post:
      operationId: webauthnVerifyStep
      tags:
        - Interaction
      summary: Complete passkey authentication
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). credential is the PublicKeyCredential JSON from the browser or platform API
        (required).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                credential:
                  type: object
                  additionalProperties: true
              required:
                - credential
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/webauthn/registration-options:
    post:
      operationId: webauthnRegistrationOptionsStep
      tags:
        - Interaction
      summary: Begin passkey registration
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). The body must be an empty JSON object (or empty).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: >-
          Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected. The body may
          be empty (treated as {}), but Content-Type: application/json is still required.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/webauthn/register:
    post:
      operationId: webauthnRegisterStep
      tags:
        - Interaction
      summary: Complete passkey registration
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). credential is the attestation PublicKeyCredential JSON (required).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                credential:
                  type: object
                  additionalProperties: true
                name:
                  type: string
              required:
                - credential
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/password/update:
    post:
      operationId: updatePasswordStep
      tags:
        - Interaction
      summary: Set a new password (required action)
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                new_password:
                  type: string
                  format: password
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/terms:
    post:
      operationId: acceptTermsStep
      tags:
        - Interaction
      summary: Accept terms
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/cancel-deletion:
    post:
      operationId: cancelDeletionStep
      tags:
        - Interaction
      summary: Cancel a scheduled account deletion while signing in
      description: >-
        Transaction-bound step for the cancel_deletion action (USR-012). An account with a pending self-service deletion
        completes authentication as usual (every factor it needs, MFA included); the transaction then offers only
        cancel_deletion, whose options carry deletion_scheduled_at and deletion_requested_at, and issues no session,
        code or token. This step cancels the deletion (the account is active again, audited user.deletion.cancelled with
        via sign_in) and the transaction continues to its normal completion: the state may carry further actions or
        redirect_to (and browser callers receive the pa_sid cookie while pa_tx is cleared). 409 unexpected_step when the
        transaction is not at cancel_deletion (factors still missing, or no deletion pending); 409 conflict when the
        deletion was cancelled or completed meanwhile. The body is an empty JSON object.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/profile:
    post:
      operationId: completeProfileStep
      tags:
        - Interaction
      summary: Complete required profile fields
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type:
                    - object
                    - 'null'
                  additionalProperties: true
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/organization:
    post:
      operationId: selectOrganizationStep
      tags:
        - Interaction
      summary: Select organization
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organization_id:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/consent:
    post:
      operationId: consentStep
      tags:
        - Interaction
      summary: Approve or deny consent
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                approve:
                  type: boolean
                scopes:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/remember-me:
    post:
      operationId: rememberMeStep
      tags:
        - Interaction
      summary: Set remember-me preference
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                remember:
                  type: boolean
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/cancel:
    post:
      operationId: cancelTransaction
      tags:
        - Interaction
      summary: Cancel the transaction
      description: >-
        Transaction-bound step. On completion the state carries redirect_to (and browser callers receive the pa_sid
        cookie while pa_tx is cleared). The request body is ignored. Returns the cancelled state with redirect_to when
        an error redirect is possible.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/federation/start:
    post:
      operationId: startFederationStep
      tags:
        - Interaction
      summary: Start federated sign-in with an upstream provider
      description: >-
        Transaction-bound step. The returned state carries external_redirect, the upstream authorization URL the browser
        must visit.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider:
                  type: string
                  description: Identity provider alias or ID.
              required:
                - provider
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/auth/transactions/{id}/resume:
    post:
      operationId: resumeTransaction
      tags:
        - Interaction
      summary: Resume a transaction after an out-of-band step
      description: >-
        Re-evaluates the transaction after an upstream callback or SSO reuse and completes it when nothing remains. The
        body must be empty or an empty JSON object.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: >-
          Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected. The body may
          be empty (treated as {}), but Content-Type: application/json is still required.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/federation/{connection}/callback:
    get:
      operationId: federationCallbackGet
      tags:
        - Federation
      summary: Upstream callback (query response mode)
      description: >-
        Upstream authorization response endpoint registered with the identity provider. When the realm has a login UI
        the browser is redirected (303) to it with transaction_id (and federation_error); a pending link confirmation
        code travels in the URL fragment (federation_link_code). Headless realms without a login UI receive the outcome
        as JSON. Returns 404 feature_disabled when federation is not configured.
      security: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_connection'
        - $ref: '#/components/parameters/RequestId'
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: state
        - name: code
          in: query
          required: false
          schema:
            type: string
            x-secret: true
          description: code
        - name: error
          in: query
          required: false
          schema:
            type: string
          description: error
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: CallbackOutcome
                    properties:
                      transaction_id:
                        type: string
                      status:
                        type: string
                        enum:
                          - ok
                          - error
                      error:
                        type: string
                    required:
                      - status
                  - type: object
                    title: LinkPendingConfirmation
                    properties:
                      status:
                        type: string
                        const: link_pending_confirmation
                      link_code:
                        type: string
                        x-secret: true
                        description: Single-use code for POST /me/linked-identities/confirm.
                    required:
                      - status
                      - link_code
        '303':
          description: Redirect to the realm login UI.
          headers:
            Location:
              $ref: '#/components/headers/Location'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: federationCallbackPost
      tags:
        - Federation
      summary: Upstream callback (form_post response mode)
      description: >-
        Upstream authorization response endpoint registered with the identity provider. When the realm has a login UI
        the browser is redirected (303) to it with transaction_id (and federation_error); a pending link confirmation
        code travels in the URL fragment (federation_link_code). Headless realms without a login UI receive the outcome
        as JSON. Returns 404 feature_disabled when federation is not configured.
      security: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_connection'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              description: At most 64 KiB.
              properties:
                state:
                  type: string
                code:
                  type: string
                  x-secret: true
                error:
                  type: string
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: CallbackOutcome
                    properties:
                      transaction_id:
                        type: string
                      status:
                        type: string
                        enum:
                          - ok
                          - error
                      error:
                        type: string
                    required:
                      - status
                  - type: object
                    title: LinkPendingConfirmation
                    properties:
                      status:
                        type: string
                        const: link_pending_confirmation
                      link_code:
                        type: string
                        x-secret: true
                        description: Single-use code for POST /me/linked-identities/confirm.
                    required:
                      - status
                      - link_code
        '303':
          description: Redirect to the realm login UI.
          headers:
            Location:
              $ref: '#/components/headers/Location'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/registrations:
    post:
      operationId: register
      tags:
        - Interaction
      summary: Register a new account
      description: >-
        Account creation within a transaction (REG-001). The response is identical whether or not the address already
        belongs to an account. Requires transaction continuation authority.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                display_name:
                  type: string
                email:
                  type: string
                family_name:
                  type: string
                given_name:
                  type: string
                invitation:
                  type: string
                  x-secret: true
                  description: Invitation secret to accept during registration.
                locale:
                  type: string
                organization:
                  oneOf:
                    - $ref: '#/components/schemas/OrganizationInput'
                    - type: 'null'
                password:
                  type: string
                  format: password
                profile:
                  additionalProperties: {}
                  type:
                    - object
                    - 'null'
                terms_version:
                  type: string
                username:
                  type: string
                transaction_id:
                  type: string
                  description: Transaction to continue.
              type: object
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/password-resets:
    post:
      operationId: requestPasswordReset
      tags:
        - Interaction
      summary: Request a password reset
      description: Always returns the same generic response (no account enumeration).
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                identifier:
                  type: string
                locale:
                  type: string
              additionalProperties: false
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordResetRequested'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/password-resets/complete:
    post:
      operationId: completePasswordReset
      tags:
        - Interaction
      summary: Complete a password reset
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reset_id:
                  type: string
                code:
                  type: string
                  x-secret: true
                new_password:
                  type: string
                  format: password
              required:
                - reset_id
                - code
                - new_password
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: password_reset
                  mfa_unchanged:
                    type: boolean
                    const: true
                required:
                  - status
                  - mfa_unchanged
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/account-setup:
    post:
      operationId: completeAccountSetup
      tags:
        - Interaction
      summary: Complete administrator-initiated account setup
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                setup_token:
                  type: string
                  x-secret: true
                password:
                  type: string
                  format: password
              required:
                - setup_token
                - password
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: account_ready
                required:
                  - status
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me:
    get:
      operationId: getMe
      tags:
        - Self-service
      summary: Get own profile
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: updateMe
      tags:
        - Self-service
      summary: Update own profile
      description: Field-level policy and the realm attribute schema apply.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchOptional'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfilePatch'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfUser'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/identifiers:
    get:
      operationId: listMyIdentifiers
      tags:
        - Self-service
      summary: List own identifiers
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserIdentifier'
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: addMyIdentifier
      tags:
        - Self-service
      summary: Add an identifier
      description: Requires recent authentication. The identifier is unverified until proven with a verification challenge.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - email
                    - phone
                    - username
                value:
                  type: string
              required:
                - type
                - value
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  type:
                    type: string
                  value:
                    type: string
                  verified:
                    type: boolean
                    const: false
                  next:
                    type: string
                required:
                  - id
                  - type
                  - value
                  - verified
                  - next
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/identifiers/{id}:
    delete:
      operationId: removeMyIdentifier
      tags:
        - Self-service
      summary: Remove an identifier
      description: Requires recent authentication.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/identifiers/{id}/primary:
    post:
      operationId: makeIdentifierPrimary
      tags:
        - Self-service
      summary: Make an identifier primary
      description: Requires recent authentication.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/verification-challenges:
    post:
      operationId: createVerificationChallenge
      tags:
        - Self-service
      summary: Request identifier verification
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                identifier_id:
                  type: string
              required:
                - identifier_id
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  challenge_id:
                    type: string
                required:
                  - challenge_id
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/verification-challenges/{id}/consume:
    post:
      operationId: consumeVerificationChallenge
      tags:
        - Self-service
      summary: Complete identifier verification
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
              required:
                - code
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  verified:
                    type: boolean
                    const: true
                required:
                  - verified
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/password:
    post:
      operationId: changeMyPassword
      tags:
        - Self-service
      summary: Change own password
      description: Requires recent authentication.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                current_password:
                  type: string
                  format: password
                new_password:
                  type: string
                  format: password
              required:
                - current_password
                - new_password
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: password_changed
                required:
                  - status
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/credentials:
    get:
      operationId: listMyCredentials
      tags:
        - Self-service
      summary: List own authenticators (safe metadata)
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SelfCredential'
                  recovery_codes_remaining:
                    type: integer
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/credentials/{id}:
    delete:
      operationId: removeMyCredential
      tags:
        - Self-service
      summary: Remove an authenticator
      description: >-
        Requires recent authentication. The password cannot be removed, and the last factor cannot be removed when MFA
        is mandatory (last_sign_in_method).
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/webauthn:
    get:
      operationId: listMyPasskeys
      tags:
        - Self-service
      summary: List own passkeys
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Passkey'
                  rp_id:
                    type: string
                    description: Effective WebAuthn relying party ID for the realm.
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/webauthn/registration-options:
    post:
      operationId: beginMyPasskeyRegistration
      tags:
        - Self-service
      summary: Begin passkey enrollment
      description: >-
        Requires recent authentication. The body must be empty or an empty JSON object. Returns 404 feature_disabled
        unless passkeys are enabled for sign-in or allowed as an MFA factor.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected. The body may
          be empty (treated as {}), but Content-Type: application/json is still required.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyRegistrationOptions'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/webauthn/registration-complete:
    post:
      operationId: completeMyPasskeyRegistration
      tags:
        - Self-service
      summary: Finish passkey enrollment
      description: Requires recent authentication. A successful enrollment steps up the current session and notifies the user.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ceremony_id:
                  type: string
                credential:
                  type: object
                  description: Attestation PublicKeyCredential JSON from navigator.credentials.create() or the platform API.
                name:
                  type: string
              required:
                - ceremony_id
                - credential
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Passkey'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/webauthn/{id}:
    patch:
      operationId: renameMyPasskey
      tags:
        - Self-service
      summary: Rename a passkey
      description: Passkeys are removed with DELETE /me/credentials/{id}.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
                - name
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/linked-identities:
    get:
      operationId: listMyLinkedIdentities
      tags:
        - Federation
      summary: List own linked external identities
      description: Returns an empty list when federation is not configured.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/LinkedIdentity'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: beginMyIdentityLink
      tags:
        - Federation
      summary: Start linking an external identity
      description: >-
        Requires recent authentication. The upstream callback returns a link confirmation code to finish with POST
        /me/linked-identities/confirm.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider:
                  type: string
                  description: Identity provider alias or ID.
              required:
                - provider
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  authorization_url:
                    type: string
                    format: uri
                    description: Upstream authorization URL to visit to prove control.
                  expires_in:
                    type: integer
                required:
                  - authorization_url
                  - expires_in
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/linked-identities/confirm:
    post:
      operationId: confirmMyIdentityLink
      tags:
        - Federation
      summary: Confirm a pending identity link
      description: Requires recent authentication.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  x-secret: true
              required:
                - code
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkedIdentity'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/linked-identities/{id}:
    delete:
      operationId: unlinkMyIdentity
      tags:
        - Federation
      summary: Unlink an external identity
      description: Requires recent authentication. The last viable sign-in method cannot be removed.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/totp/enroll:
    post:
      operationId: beginMyTOTPEnrollment
      tags:
        - Self-service
      summary: Begin TOTP enrollment
      description: Requires recent authentication. Any request body is ignored.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TOTPEnrollment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/totp/activate:
    post:
      operationId: activateMyTOTP
      tags:
        - Self-service
      summary: Activate TOTP
      description: >-
        Requires recent authentication. Restores normal privileges for a recovery-restricted session. recovery_codes are
        returned once.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
              required:
                - code
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: totp_enrolled
                  recovery_codes:
                    type:
                      - array
                      - 'null'
                    items:
                      type: string
                    x-secret: true
                required:
                  - status
                  - recovery_codes
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/totp:
    delete:
      operationId: removeMyTOTP
      tags:
        - Self-service
      summary: Remove TOTP
      description: Requires recent authentication.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/hotp/enroll:
    post:
      operationId: beginMyHOTPEnrollment
      tags:
        - Self-service
      summary: Begin HOTP enrollment
      description: >-
        Optional counter-based tokens (MFA-013): 409 unless the realm lists hotp in mfa.allowed_factors. Requires recent
        authentication and, when the account already has a second factor the realm allows, a session that proved one
        (MFA-006). A recovery-restricted session may enroll (MFA-010). Any request body is ignored. The secret and
        otpauth://hotp URI (counter 0) are returned once.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HOTPEnrollment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/hotp/activate:
    post:
      operationId: activateMyHOTP
      tags:
        - Self-service
      summary: Activate HOTP
      description: >-
        Verifies a code within mfa.hotp.look_ahead counters of 0 and activates the token (replacing an active one); the
        counter moves past the code. Requires recent authentication. Restores normal privileges for a
        recovery-restricted session. recovery_codes are returned once, only when the account had none.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
              required:
                - code
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: hotp_enrolled
                  recovery_codes:
                    type:
                      - array
                      - 'null'
                    items:
                      type: string
                    x-secret: true
                required:
                  - status
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/hotp/resync:
    post:
      operationId: resyncMyHOTP
      tags:
        - Self-service
      summary: Resynchronize an HOTP token
      description: >-
        Realigns the stored counter with a token pressed beyond the sign-in look-ahead (MFA-013): code and next_code
        must be two consecutive codes within mfa.hotp.resync_window counters of the stored one; the counter only moves
        forward. A single code that far ahead is never accepted. Requires recent authentication and a session that
        completed MFA (403 mfa_required otherwise); at most 5 attempts per 15 minutes (fails closed). Audited as
        mfa.hotp.resynchronized or mfa.hotp.resync_failed.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                next_code:
                  type: string
              required:
                - code
                - next_code
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: hotp_resynchronized
                required:
                  - status
        '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/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/hotp:
    delete:
      operationId: removeMyHOTP
      tags:
        - Self-service
      summary: Remove HOTP
      description: >-
        Requires recent authentication. Refused (409 last_sign_in_method) when it is the last second factor of an
        account that must use MFA (only factors the realm allows count as remaining; a token the realm no longer allows
        can always be removed); remembered devices are forgotten.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/recovery-codes/regenerate:
    post:
      operationId: regenerateMyRecoveryCodes
      tags:
        - Self-service
      summary: Replace recovery codes
      description: Requires authentication within the last 5 minutes from an MFA session. Any request body is ignored.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  recovery_codes:
                    type:
                      - array
                      - 'null'
                    items:
                      type: string
                    x-secret: true
                    description: New recovery codes; returned once. Previous codes are invalidated.
                required:
                  - recovery_codes
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/sessions:
    get:
      operationId: listMySessions
      tags:
        - Self-service
      summary: List own sessions
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SelfSession'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/sessions/{id}:
    delete:
      operationId: revokeMySession
      tags:
        - Self-service
      summary: Revoke one own session
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/sessions/revoke-all:
    post:
      operationId: revokeAllMySessions
      tags:
        - Self-service
      summary: Revoke all own sessions
      description: Any request body is ignored.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokedSessions'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/organizations:
    get:
      operationId: listMyOrganizations
      tags:
        - Self-service
      summary: List own memberships
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/MembershipSummary'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/organization-grants:
    post:
      operationId: switchOrganization
      tags:
        - Self-service
      summary: Switch organization context
      description: >-
        Issues a new authorization code for the calling client bound to the current session after checking active
        membership and organization MFA/SSO requirements (TEN-005). offline_access is never included. A client that must
        use pushed authorization requests (security_profile fapi2 or high_assurance, or token_policy.require_par) is
        refused with 403: the code would be issued outside PAR (and, for fapi2, the profile's 60-second code lifetime),
        so it switches with a new pushed authorization request naming the organization (ADV-001).
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                organization_id:
                  type: string
                redirect_uri:
                  type: string
                code_challenge:
                  type: string
                  minLength: 43
                  maxLength: 43
                code_challenge_method:
                  type: string
                  const: S256
                scope:
                  type: string
                resource:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                nonce:
                  type: string
                state:
                  type: string
              required:
                - client_id
                - organization_id
                - redirect_uri
                - code_challenge
                - code_challenge_method
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  redirect_to:
                    type: string
                    format: uri
                    description: Redirect URI carrying a new authorization code bound to the current session.
                required:
                  - redirect_to
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/permissions:
    get:
      operationId: getMyPermissions
      tags:
        - Self-service
      summary: Inspect own effective permissions
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
          description: Evaluate in this organization (requires active membership).
        - name: project_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Evaluate for a resource of this project: the caller's project-scoped role assignments for it count too
            (AZ-002). The project must exist and, with organization_id, belong to that organization (owned, or shared
            through an active project grant); otherwise 422.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EffectivePermissions'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/consents:
    get:
      operationId: listMyConsents
      tags:
        - Self-service
      summary: List own consents
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Consent'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/consents/{id}:
    delete:
      operationId: revokeMyConsent
      tags:
        - Self-service
      summary: Revoke a consent
      description: Also revokes the client's active grants for the user.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/security-events:
    get:
      operationId: listMySecurityEvents
      tags:
        - Self-service
      summary: View own security history
      description: Most recent 100 security, support, account and token events.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SecurityEvent'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/deletion-request:
    post:
      operationId: requestMyDeletion
      tags:
        - Self-service
      summary: Request account deletion
      description: >-
        Requires recent authentication. Last owners must transfer ownership first (last_owner). Any request body is
        ignored. The account becomes pending_deletion, every session and grant (offline ones included) is revoked, and
        the deletion_scheduled notice is queued to the verified primary email in the same transaction. Until
        privacy.deletion_grace_period ends the owner can cancel by signing in: after the usual factors the
        authentication transaction offers only the cancel_deletion action (POST
        /auth/transactions/{id}/cancel-deletion), and no session or token is issued unless the deletion is cancelled
        (USR-012).
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                  deletion_scheduled_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                required:
                  - state
                  - deletion_scheduled_at
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: cancelMyDeletion
      tags:
        - Self-service
      summary: Cancel account deletion
      description: >-
        Kept for compatibility. A pending-deletion account holds no session (the request revoked them all and none is
        issued while it is pending), so owners cancel while signing in with the cancel_deletion transaction step (POST
        /auth/transactions/{id}/cancel-deletion, USR-012). 409 when no deletion is pending.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/personal-tokens:
    get:
      operationId: listMyPersonalTokens
      tags:
        - Self-service
      summary: List personal access tokens
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/MachineCredential'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createMyPersonalToken
      tags:
        - Self-service
      summary: Create a personal access token
      description: Requires recent authentication. Bounded by the caller's own grant ceiling; expiry is mandatory.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MachineCredentialInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    x-secret: true
                    description: >-
                      Personal access token (pa_pat_ prefix). Returned exactly once; it is never stored in plaintext,
                      never shown again and never replayed from the idempotency store.
                  credential:
                    $ref: '#/components/schemas/MachineCredential'
                  notice:
                    type: string
                required:
                  - token
                  - credential
                  - notice
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/personal-tokens/{id}:
    delete:
      operationId: revokeMyPersonalToken
      tags:
        - Self-service
      summary: Revoke a personal access token
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/impersonation-grants:
    get:
      operationId: listMySupportGrants
      tags:
        - Self-service
      summary: View support access to own account
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerSupportGrant'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/impersonation-grants/{id}/revoke:
    post:
      operationId: revokeMySupportGrant
      tags:
        - Self-service
      summary: End support access
      description: Any request body is ignored.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/support-access:
    put:
      operationId: setMySupportAccess
      tags:
        - Self-service
      summary: Opt out of (or back into) support access
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                opt_out:
                  type: boolean
              required:
                - opt_out
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  opt_out:
                    type: boolean
                required:
                  - opt_out
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/exports:
    post:
      operationId: requestMyDataExport
      tags:
        - Self-service
      summary: Request a personal data export
      description: >-
        Requires recent authentication. Creates a user.export job; download the protected result through the job
        download endpoints.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations:
    get:
      operationId: listOrganizations
      tags:
        - Organizations
      summary: List organizations
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - realm.organizations.read (otherwise own memberships)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Search text (realm-wide listing only).
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: 'Callers holding realm.organizations.read: paginated realm-wide list.'
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/Organization'
                      next_cursor:
                        type: string
                        description: >-
                          Opaque cursor for the next page; an empty string when there are no more results. Cursors are
                          bound to the realm and listing and cannot be replayed elsewhere.
                    required:
                      - items
                      - next_cursor
                  - type: object
                    description: 'Other users: the caller''s own memberships (not paginated).'
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/MembershipSummary'
                    required:
                      - items
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createOrganization
      tags:
        - Organizations
      summary: Create an organization
      description: >-
        Allowed for holders of realm.organizations.create, or for users when the realm policy allows self-service
        organization creation (the creator becomes owner).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - realm.organizations.create
        - realm policy registration.allow_organization_creation (users)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: join
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: With true, a realm administrator creating the organization also becomes its owner.
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          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'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}:
    get:
      operationId: getOrganization
      tags:
        - Organizations
      summary: Get an organization
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: updateOrganization
      tags:
        - Organizations
      summary: Update an organization
      description: >-
        If-Match is required when the body changes policy (428 precondition_required without it, 412 when stale;
        API-010); it is optional for other fields.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.update
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchOptional'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            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'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteOrganization
      tags:
        - Organizations
      summary: Delete an organization (asynchronous)
      description: >-
        Revokes access immediately and starts an organization.delete job that cannot be cancelled. Users need recent
        authentication.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.delete
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    const: deleting
                  job_id:
                    type: string
                required:
                  - state
                  - job_id
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/deletion-preview:
    get:
      operationId: previewOrganizationDeletion
      tags:
        - Organizations
      summary: Preview organization deletion impact
      description: >-
        Counts what deleting the organization (TEN-024) would revoke, disable, erase or keep, without changing anything.
        active_legal_holds counts the holds that keep its evidence: realm-wide holds, holds on the organization and
        holds on any account that is (or was) a member.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.delete
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationDeletionPreview'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/archive:
    post:
      operationId: archiveOrganization
      tags:
        - Organizations
      summary: Archive an organization
      description: >-
        Archiving (TEN-001) revokes the organization's sessions and grants like suspension and keeps its records and
        audit history. Requires realm.organizations.suspend and (for users) an MFA session. Note: the body is decoded
        leniently (decode errors are ignored).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - realm.organizations.suspend
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    const: archived
                required:
                  - state
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/suspend:
    post:
      operationId: suspendOrganization
      tags:
        - Organizations
      summary: Suspend an organization
      description: >-
        Requires realm.organizations.suspend and (for users) an MFA session. Note: the body is decoded leniently (decode
        errors are ignored).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - realm.organizations.suspend
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    const: suspended
                required:
                  - state
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/reactivate:
    post:
      operationId: reactivateOrganization
      tags:
        - Organizations
      summary: Reactivate an organization
      description: >-
        Requires realm.organizations.suspend and (for users) an MFA session. Note: the body is decoded leniently (decode
        errors are ignored).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - realm.organizations.suspend
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    const: active
                required:
                  - state
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/ownership-transfers:
    post:
      operationId: transferOrganizationOwnership
      tags:
        - Organizations
      summary: Transfer ownership
      description: Users need recent authentication.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.ownership.transfer
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                membership_id:
                  type: string
                release_current_owner:
                  type: boolean
              required:
                - membership_id
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: transferred
                required:
                  - status
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/members:
    get:
      operationId: listMembers
      tags:
        - Organizations
      summary: List members
      description: >-
        Email local parts are masked unless the caller holds realm.users.read. Each membership's metadata (USR-009) is
        included only when the caller holds org.members.write in the organization.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.members.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: Filter by membership state; removed and expired members are hidden by default.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Membership'
                  next_cursor:
                    type: string
                    description: >-
                      Opaque cursor for the next page; an empty string when there are no more results. Cursors are bound
                      to the realm and listing and cannot be replayed elsewhere.
                required:
                  - items
                  - next_cursor
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: addMember
      tags:
        - Organizations
      summary: Add a member
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.members.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                role_ids:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
              required:
                - user_id
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/members/{membership}:
    get:
      operationId: getMember
      tags:
        - Organizations
      summary: Get a membership
      description: >-
        The membership's metadata (USR-009) is included only when the caller holds org.members.write in the
        organization.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.members.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_membership'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  membership:
                    $ref: '#/components/schemas/Membership'
                  role_assignments:
                    type:
                      - array
                      - 'null'
                    items:
                      $ref: '#/components/schemas/RoleAssignment'
                required:
                  - membership
                  - role_assignments
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: updateMember
      tags:
        - Organizations
      summary: Suspend or reactivate a membership, or edit its metadata
      description: >-
        Changes state, metadata or both, atomically. metadata is the organization's own data about the membership
        (USR-009), separate from the user's profile, admin_metadata and internal metadata: it is merged (a key set to
        null is removed), must stay within limits.metadata_bytes as JSON (422 on metadata), is returned to callers
        holding org.members.write, never to the member or in tokens, is audited as
        organization.membership.metadata_updated with the key names only, and is erased when the membership ends or the
        account is deleted. The member-management ceiling applies (an administrator cannot act on a member holding
        organization permissions the administrator lacks). 409 for a removed or expired membership; 422 when neither
        field is given.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.members.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_membership'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                state:
                  type: string
                  enum:
                    - active
                    - suspended
                metadata:
                  type:
                    - object
                    - 'null'
                  additionalProperties: true
                  description: Keys to set; a key whose value is null is removed. Omitted or null leaves the metadata unchanged.
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: removeMember
      tags:
        - Organizations
      summary: Remove a member (or leave)
      description: Members may remove themselves; otherwise org.members.write is required. The last owner cannot be removed.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.members.write (not needed to remove oneself)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_membership'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/members/{membership}/roles:
    post:
      operationId: assignMemberRole
      tags:
        - Organizations
      summary: Assign an organization role to a member
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.roles.assign
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_membership'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role_id:
                  type: string
                expires_at:
                  type:
                    - string
                    - 'null'
                  format: date-time
                approver_id:
                  type: string
                reason:
                  type: string
              required:
                - role_id
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleAssignment'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/members/{membership}/roles/{assignment}:
    delete:
      operationId: unassignMemberRole
      tags:
        - Organizations
      summary: Remove a member role assignment
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.roles.assign
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_membership'
        - $ref: '#/components/parameters/Path_assignment'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/roles:
    get:
      operationId: listOrganizationRoles
      tags:
        - Organizations
      summary: List organization roles
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createOrganizationRole
      tags:
        - Organizations
      summary: Create an organization role
      description: boundary_type and organization_id are forced to this organization.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.roles.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/roles/{role}/permissions:
    post:
      operationId: modifyOrganizationRolePermissions
      tags:
        - Organizations
      summary: Change organization role permissions
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.roles.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_role'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                add:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                remove:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/invitations:
    get:
      operationId: listInvitations
      tags:
        - Invitations
      summary: List invitations
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.invites.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: Filter by invitation state.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invitation'
                  next_cursor:
                    type: string
                    description: >-
                      Opaque cursor for the next page; an empty string when there are no more results. Cursors are bound
                      to the realm and listing and cannot be replayed elsewhere.
                required:
                  - items
                  - next_cursor
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createInvitation
      tags:
        - Invitations
      summary: Create an invitation
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.invites.create
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvitationInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  invitation:
                    $ref: '#/components/schemas/Invitation'
                  invitation_secret:
                    type: string
                    x-secret: true
                    description: >-
                      Shared-link secret (only for purpose shared_link; mailed invitations never return it). Returned
                      exactly once; it is never stored in plaintext, never shown again and never replayed from the
                      idempotency store.
                required:
                  - 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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/invitations/{id}/resend:
    post:
      operationId: resendInvitation
      tags:
        - Invitations
      summary: Rotate and resend an invitation
      description: Any request body is ignored.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.invites.create
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: resent
                required:
                  - status
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/invitations/{id}/revoke:
    post:
      operationId: revokeInvitation
      tags:
        - Invitations
      summary: Revoke an invitation
      description: Any request body is ignored.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.invites.revoke
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/invitations/inspect:
    post:
      operationId: inspectInvitation
      tags:
        - Invitations
      summary: Inspect an invitation without consuming it
      description: Invalid, expired and used invitations return the same error.
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invitation:
                  type: string
                  x-secret: true
              required:
                - invitation
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationInspection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/invitations/accept:
    post:
      operationId: acceptInvitation
      tags:
        - Invitations
      summary: Accept an invitation
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invitation:
                  type: string
                  x-secret: true
              required:
                - invitation
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationAcceptance'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/invitations/decline:
    post:
      operationId: declineInvitation
      tags:
        - Invitations
      summary: Decline an invitation
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invitation:
                  type: string
                  x-secret: true
              required:
                - invitation
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/join-requests:
    get:
      operationId: listJoinRequests
      tags:
        - Organizations
      summary: List join requests
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.join_requests.review
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: Filter by state.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/JoinRequest'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: requestToJoin
      tags:
        - Organizations
      summary: Request to join an organization
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected. The body may
          be empty (treated as {}), but Content-Type: application/json is still required.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JoinRequest'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/join-requests/{id}/decision:
    post:
      operationId: decideJoinRequest
      tags:
        - Organizations
      summary: Approve or deny a join request
      description: Reviewers cannot approve their own requests.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.join_requests.review
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                approve:
                  type: boolean
                reason:
                  type: string
              required:
                - approve
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/groups:
    get:
      operationId: listGroups
      tags:
        - Organizations
      summary: List groups
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createGroup
      tags:
        - Organizations
      summary: Create a group
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/groups/{group}:
    get:
      operationId: getGroup
      tags:
        - Organizations
      summary: Get a group
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_group'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: updateGroup
      tags:
        - Organizations
      summary: Update a group
      description: 'Note: unlike GET, the response does not carry an ETag.'
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_group'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchOptional'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteGroup
      tags:
        - Organizations
      summary: Delete a group
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_group'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/groups/{group}/members:
    get:
      operationId: listGroupMembers
      tags:
        - Organizations
      summary: List group members
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_group'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/GroupMember'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: addGroupMember
      tags:
        - Organizations
      summary: Add a group member
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_group'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                membership_id:
                  type: string
              required:
                - membership_id
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/groups/{group}/members/{member}:
    delete:
      operationId: removeGroupMember
      tags:
        - Organizations
      summary: Remove a group member
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_group'
        - $ref: '#/components/parameters/Path_member'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/groups/{group}/roles:
    post:
      operationId: assignGroupRole
      tags:
        - Organizations
      summary: Assign an organization role to a group
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.roles.assign
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_group'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role_id:
                  type: string
              required:
                - role_id
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleAssignment'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/domains:
    get:
      operationId: listDomains
      tags:
        - Organizations
      summary: List domains
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.domains.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Domain'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: addDomain
      tags:
        - Organizations
      summary: Claim a domain
      description: Returns the DNS TXT challenge to publish.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.domains.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  type: string
              required:
                - domain
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainChallenge'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/domains/{id}/verify:
    post:
      operationId: verifyDomain
      tags:
        - Organizations
      summary: Verify domain control
      description: Any request body is ignored.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.domains.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/domains/{id}:
    patch:
      operationId: updateOrganizationDomain
      tags:
        - Organizations
      summary: Change domain routing
      description: >-
        With include_subdomains a verified domain also routes sign-ins from its subdomains (TEN-011). Routing is
        deterministic: an exactly matching verified domain always wins, otherwise the most specific parent that opted
        in; verified domains are unique in the realm.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.domains.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                include_subdomains:
                  type: boolean
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: removeDomain
      tags:
        - Organizations
      summary: Remove a domain
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.domains.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/organizations/{org}/audit-events:
    get:
      operationId: listOrganizationAuditEvents
      tags:
        - Audit
      summary: Query organization audit events
      description: >-
        Filters combine with AND. Type prefixes are literal, including underscores, percent and backslash. Keep filters
        while following next_cursor; only limit may change. A cursor from another route, organization or filter set
        returns 400.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.audit.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: id
          in: query
          required: false
          schema:
            type: string
          description: One event by ID (evt_...), for example the audit_event_id of a security.alert.
        - name: actor_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by actor.
        - name: subject_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by subject.
        - name: type
          in: query
          required: false
          schema:
            type: string
          description: Exact event type.
        - name: type_prefix
          in: query
          required: false
          schema:
            type: string
          description: Literal event type prefix; percent, underscore and backslash have no wildcard or escape meaning.
        - name: outcome
          in: query
          required: false
          schema:
            type: string
          description: success, denied or failure.
        - name: client_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by client.
        - name: request_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by request ID.
        - name: impersonation_grant_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by support grant.
        - name: grant_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by authorization grant.
        - name: session_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by session (the event session or the acting session).
        - name: target_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by target object ID.
        - name: category
          in: query
          required: false
          schema:
            type: string
          description: Filter by audit category (security, configuration, operations, emergency, ...).
        - name: network
          in: query
          required: false
          schema:
            type: string
          description: IP address or CIDR prefix; matches events whose stored, truncated network context overlaps it (AUD-011).
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: RFC 3339 lower bound.
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: RFC 3339 upper bound.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditEvent'
                  next_cursor:
                    type: string
                    description: >-
                      Opaque cursor for the next page; an empty string when there are no more results. Cursors are bound
                      to the realm and listing and cannot be replayed elsewhere.
                required:
                  - items
                  - next_cursor
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users:
    get:
      operationId: listUsers
      tags:
        - Users
      summary: Search users
      description: Requires realm.users.read; holders of only support.users.read receive masked views.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
        - support.users.read (masked view)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Search text.
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: Filter by state.
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
          description: Only members of this organization.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/AdminUser'
                        - $ref: '#/components/schemas/MaskedUser'
                  next_cursor:
                    type: string
                    description: >-
                      Opaque cursor for the next page; an empty string when there are no more results. Cursors are bound
                      to the realm and listing and cannot be replayed elsewhere.
                required:
                  - items
                  - next_cursor
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createUser
      tags:
        - Users
      summary: Create a user
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                username:
                  type: string
                phone:
                  type: string
                  description: E.164.
                display_name:
                  type: string
                given_name:
                  type: string
                family_name:
                  type: string
                locale:
                  type: string
                admin_metadata:
                  type:
                    - object
                    - 'null'
                  additionalProperties: true
                send_setup_email:
                  type:
                    - boolean
                    - 'null'
                  description: Defaults to true. When false (or no email), a setup token is returned once.
                required_actions:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                    enum:
                      - update_password
                      - verify_email
                      - configure_totp
                      - accept_terms
                      - complete_profile
                      - verify_contact
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/AdminUser'
                  setup_token:
                    type: string
                    x-secret: true
                    description: >-
                      One-time account setup token (72 hours) for delivery through a trusted channel; only when no setup
                      email is sent. Returned exactly once; it is never stored in plaintext, never shown again and never
                      replayed from the idempotency store.
                  notice:
                    type: string
                required:
                  - user
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}:
    get:
      operationId: getUser
      tags:
        - Users
      summary: Get a user
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
        - support.users.read (masked view)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AdminUser'
                  - $ref: '#/components/schemas/MaskedUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: updateUser
      tags:
        - Users
      summary: Update a user
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchOptional'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminUserPatch'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminUser'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteUser
      tags:
        - Users
      summary: Delete a user immediately
      description: Administrators cannot delete themselves (409).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.delete
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/suspend:
    post:
      operationId: suspendUser
      tags:
        - Users
      summary: Suspend a user account
      description: >-
        Global-account authority (realm.users.suspend), not tenant membership administration. Administrators cannot
        change their own state. Note: the body is decoded leniently (decode errors are ignored).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.suspend
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminUser'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/reactivate:
    post:
      operationId: reactivateUser
      tags:
        - Users
      summary: Reactivate a user account
      description: >-
        Global-account authority (realm.users.suspend), not tenant membership administration. Administrators cannot
        change their own state. Note: the body is decoded leniently (decode errors are ignored).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.suspend
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminUser'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/lock:
    post:
      operationId: lockUser
      tags:
        - Users
      summary: Lock a user account
      description: >-
        Global-account authority (realm.users.suspend), not tenant membership administration. Administrators cannot
        change their own state. Note: the body is decoded leniently (decode errors are ignored).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.suspend
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminUser'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/required-actions:
    post:
      operationId: setUserRequiredActions
      tags:
        - Users
      summary: Set required actions
      description: >-
        Replaces the account's required actions (AUT-018). The change applies only if the list is still the one the
        request read (409 conflict otherwise, "the required actions changed concurrently; retry") and, when If-Match
        carries the ETag from GET /users/{user}, only if the account is still at that version (412 otherwise), so a
        client that reads the list, edits it and writes it back cannot overwrite a concurrent change (SEC-008). Each
        action added or removed needs its own permission besides realm.users.required_actions. The response carries the
        account's new ETag.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.required_actions
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                actions:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                    enum:
                      - update_password
                      - verify_email
                      - configure_totp
                      - accept_terms
                      - complete_profile
                      - verify_contact
              required:
                - actions
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/revoke-sessions:
    post:
      operationId: revokeUserSessions
      tags:
        - Users
      summary: Revoke all sessions of a user
      description: Any request body is ignored.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.sessions.revoke
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokedSessions'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/sessions:
    get:
      operationId: listUserSessions
      tags:
        - Users
      summary: List sessions of a user
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Session'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/verification-overrides:
    post:
      operationId: overrideIdentifierVerification
      tags:
        - Users
      summary: Mark an identifier verified (override)
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.verification.override
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                identifier_id:
                  type: string
                reason:
                  type: string
              required:
                - identifier_id
                - reason
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/identifiers:
    post:
      operationId: addUserIdentifier
      tags:
        - Users
      summary: Add an email address to an account (lost contact address)
      description: >-
        Lost contact address recovery (MFA-008): adds an email address the owner can still reach, unverified and not
        primary (USR-004). Verify it with POST /users/{user}/verification-overrides, then make it primary with POST
        /users/{user}/identifiers/{id}/primary. Requires both permissions, an MFA session with recent authentication,
        and a reason; administrators cannot change their own identifiers here. An address another account has verified
        answers 409. Audited as user.identifier.added (reason in metadata); the account's verified primary address
        receives an identifier_changed notice that does not name the new address.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.verification.override
        - realm.users.credentials.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - email
                value:
                  type: string
                  format: email
                reason:
                  type: string
                  minLength: 5
                  maxLength: 500
              required:
                - type
                - value
                - reason
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  type:
                    type: string
                    const: email
                  value:
                    type: string
                  verified:
                    type: boolean
                    const: false
                  is_primary:
                    type: boolean
                    const: false
                  next:
                    type: string
                required:
                  - id
                  - type
                  - value
                  - verified
                  - is_primary
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/identifiers/{id}/primary:
    post:
      operationId: makeUserIdentifierPrimary
      tags:
        - Users
      summary: Make a verified email address the account's primary address
      description: >-
        Lost contact address recovery (MFA-008): the primary email address receives assisted recovery's setup link and
        the owner's notices. Only a verified email address can become primary (422 otherwise; 409 when it already is).
        Requires both permissions, an MFA session with recent authentication, and a reason; administrators cannot change
        their own identifiers here. Audited as user.identifier.primary_changed (reason and previous_identifier_id in
        metadata); the previous verified primary address receives an identifier_changed notice that does not name the
        new address.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.verification.override
        - realm.users.credentials.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  minLength: 5
                  maxLength: 500
              required:
                - reason
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/credentials/password/compromised:
    post:
      operationId: markPasswordCompromised
      tags:
        - Users
      summary: Mark the password compromised
      description: 'Note: the body is decoded leniently (decode errors are ignored).'
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.credentials.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/recovery-requests:
    post:
      operationId: startAssistedRecovery
      tags:
        - Users
      summary: Start assisted account recovery
      description: >-
        Revokes sessions, optionally resets MFA (requires realm.users.credentials.manage), notifies the user and issues
        a setup link delivered to the primary email address. Operators cannot assist their own recovery. 409 when the
        primary email address is not verified: recovery is never delivered to an unverified address (verify it with POST
        /users/{user}/verification-overrides, or make a verified address primary with POST
        /users/{user}/identifiers/{id}/primary).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - support.recovery.assist
        - realm.users.credentials.manage (required for reset_mfa)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  minLength: 10
                evidence_reference:
                  type: string
                reset_mfa:
                  type: boolean
              required:
                - reason
                - evidence_reference
              additionalProperties: false
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: recovery_started
                  setup_token:
                    type: string
                    x-secret: true
                    description: >-
                      Two-hour setup token, only when the user has no email address. Returned exactly once; it is never
                      stored in plaintext, never shown again and never replayed from the idempotency store.
                required:
                  - status
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/identity-providers:
    get:
      operationId: listIdentityProviders
      tags:
        - Federation
      summary: List identity provider connections
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/IdentityProvider'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createIdentityProvider
      tags:
        - Federation
      summary: Create an identity provider connection
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProviderInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/identity-providers/{id}:
    get:
      operationId: getIdentityProvider
      tags:
        - Federation
      summary: Get an identity provider connection
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      operationId: replaceIdentityProvider
      tags:
        - Federation
      summary: Replace an identity provider connection
      description: >-
        Replaces the connection's settings (If-Match required: 428 without, 412 when stale), validated as at creation.
        alias may be omitted (kept) but cannot change (422 on alias: it is part of the registered callback URL). issuer,
        and the protocol implied by adapter, cannot change while identities are linked to the connection (409 on issuer
        or adapter; use a reviewed migration). client_secret omitted keeps the stored secret, an empty string removes it
        and a value replaces it; claim_mapping omitted keeps the current mapping, and a changed mapping increases
        mapping_revision. SAML connections are managed at /saml/connections (409 here). Audited as
        federation.provider.updated.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchRequired'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProviderInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteIdentityProvider
      tags:
        - Federation
      summary: Delete an identity provider connection
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/identity-providers/{id}/test:
    post:
      operationId: testIdentityProvider
      tags:
        - Federation
      summary: Test a connection (redacted diagnostics)
      description: Fetches discovery and keys through the egress policy without changing state. Any request body is ignored.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProviderDiagnostics'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/linked-identities:
    get:
      operationId: listUserLinkedIdentities
      tags:
        - Federation
      summary: List a user's linked identities
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/LinkedIdentity'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/users/{user}/linked-identities/{id}:
    delete:
      operationId: unlinkUserIdentity
      tags:
        - Federation
      summary: Unlink a user's external identity
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/projects:
    get:
      operationId: listProjects
      tags:
        - Projects
      summary: List projects
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.projects.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createProject
      tags:
        - Projects
      summary: Create a project
      description: >-
        Note: the request body is the Project model itself; server-managed members (id, realm_id, version, created_at,
        state) are accepted by the decoder.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.projects.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Project'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/projects/{project}:
    get:
      operationId: getProject
      tags:
        - Projects
      summary: Get a project
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.projects.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_project'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: updateProject
      tags:
        - Projects
      summary: Update a project
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.projects.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_project'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchOptional'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                state:
                  type: string
                  enum:
                    - active
                    - suspended
                    - archived
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/clients:
    get:
      operationId: listClients
      tags:
        - Clients
      summary: List clients
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Client'
                  next_cursor:
                    type: string
                    description: >-
                      Opaque cursor for the next page; an empty string when there are no more results. Cursors are bound
                      to the realm and listing and cannot be replayed elsewhere.
                required:
                  - items
                  - next_cursor
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createClient
      tags:
        - Clients
      summary: Register a client
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  client:
                    $ref: '#/components/schemas/Client'
                  client_secret:
                    type: string
                    x-secret: true
                    description: >-
                      Client secret for client_secret_* authentication. Returned exactly once; it is never stored in
                      plaintext, never shown again and never replayed from the idempotency store.
                  notice:
                    type: string
                required:
                  - client
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/clients/{client}:
    get:
      operationId: getClient
      tags:
        - Clients
      summary: Get a client
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                type: object
                properties:
                  client:
                    $ref: '#/components/schemas/Client'
                  resource_grants:
                    type:
                      - array
                      - 'null'
                    items:
                      $ref: '#/components/schemas/ResourceGrant'
                  credentials:
                    type:
                      - array
                      - 'null'
                    items:
                      $ref: '#/components/schemas/ClientCredential'
                required:
                  - client
                  - resource_grants
                  - credentials
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      operationId: replaceClient
      tags:
        - Clients
      summary: Replace a client definition
      description: client_type cannot change.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchRequired'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/clients/{client}/suspend:
    post:
      operationId: suspendClient
      tags:
        - Clients
      summary: Suspend a client
      description: 'Note: the body is decoded leniently (decode errors are ignored).'
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    const: suspended
                required:
                  - state
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/clients/{client}/reactivate:
    post:
      operationId: reactivateClient
      tags:
        - Clients
      summary: Reactivate a client
      description: >-
        Note: the body is decoded leniently (decode errors are ignored). A decommissioned client cannot be reactivated
        (409), and neither can a dynamically registered client whose registration is pending approval (409; approve it
        with POST /client-registrations/{client}/approve).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    const: active
                required:
                  - state
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/clients/{client}/decommission:
    post:
      operationId: decommissionClient
      tags:
        - Clients
      summary: Decommission a client
      description: 'Note: the body is decoded leniently (decode errors are ignored).'
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    const: decommissioned
                required:
                  - state
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/clients/{client}/credentials:
    post:
      operationId: issueClientCredential
      tags:
        - Clients
      summary: Issue a client secret or add public keys
      description: >-
        Without jwks a new secret is issued and, with retire_others_after_seconds, other secrets are scheduled for
        retirement.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.credentials
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected. The body may
          be empty (treated as {}), but Content-Type: application/json is still required.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                retire_others_after_seconds:
                  type: integer
                  minimum: 0
                jwks:
                  description: JWK Set to add for private_key_jwt; when present no secret is issued.
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: SecretIssued
                    properties:
                      client_secret:
                        type: string
                        x-secret: true
                        description: >-
                          New client secret. Returned exactly once; it is never stored in plaintext, never shown again
                          and never replayed from the idempotency store.
                      credential:
                        $ref: '#/components/schemas/ClientCredential'
                      notice:
                        type: string
                    required:
                      - client_secret
                      - credential
                      - notice
                  - type: object
                    title: KeysAdded
                    properties:
                      status:
                        type: string
                        const: keys_added
                    required:
                      - status
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/clients/{client}/credentials/{id}:
    delete:
      operationId: revokeClientCredential
      tags:
        - Clients
      summary: Revoke a client credential
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.credentials
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/clients/{client}/resource-grants/{resource}:
    get:
      operationId: getClientResourceGrant
      tags:
        - Clients
      summary: Get a client's grant for a resource
      description: Returns the grant with an entity tag; PUT honors If-Match against it (API-010).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/Path_resource'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              description: Entity tag of the grant's state.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  client_ref:
                    type: string
                  resource_id:
                    type: string
                  allowed_scopes:
                    type: array
                    items:
                      type: string
                  subject_types:
                    type: array
                    items:
                      type: string
                  exchange_policy:
                    type: object
                    additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: setClientResourceGrant
      tags:
        - Clients
      summary: Grant a client access to a resource
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/Path_resource'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                allowed_scopes:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                subject_types:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                    enum:
                      - user
                      - service_principal
                exchange_policy:
                  $ref: '#/components/schemas/ExchangePolicy'
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: removeClientResourceGrant
      tags:
        - Clients
      summary: Remove a client resource grant
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/Path_resource'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/resources:
    get:
      operationId: listResources
      tags:
        - Resources
      summary: List resources (APIs)
      description: Returns up to limits.max_page_size resources.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Resource'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createResource
      tags:
        - Resources
      summary: Register a resource (API)
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/resources/{resource}:
    get:
      operationId: getResource
      tags:
        - Resources
      summary: Get a resource
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_resource'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      operationId: replaceResource
      tags:
        - Resources
      summary: Replace a resource definition
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_resource'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchRequired'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/resources/{resource}/scopes:
    post:
      operationId: addResourceScope
      tags:
        - Resources
      summary: Add a scope to a resource
      description: >-
        Returns 201 with an empty body. Clients may request the scope only when their resource grant lists it;
        requesting a scope never grants it (APP-007). A scope declared with is_default is requested on a client's behalf
        when a request names the resource but none of its scopes, and then passes the same checks as a requested scope.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_resource'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScopeInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/scopes/{scope}:
    delete:
      operationId: deleteScope
      tags:
        - Resources
      summary: Delete a scope
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_scope'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/resources/{resource}/introspectors:
    post:
      operationId: addResourceIntrospector
      tags:
        - Resources
      summary: Authorize a client to introspect tokens for a resource
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_resource'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: Client reference.
              required:
                - client
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/permissions:
    get:
      operationId: listPermissions
      tags:
        - Authorization
      summary: List permissions
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Permission'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: registerPermission
      tags:
        - Authorization
      summary: Register a permission
      description: >-
        Note: the request body is the Permission model itself (id and built_in are accepted by the decoder). Names in
        realm., org., support. and platform. namespaces are reserved.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Permission'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Permission'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/roles:
    get:
      operationId: listRoles
      tags:
        - Authorization
      summary: List roles
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: boundary_type
          in: query
          required: false
          schema:
            type: string
          description: realm, organization or project.
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
          description: Organization roles of this organization.
        - name: project_id
          in: query
          required: false
          schema:
            type: string
          description: Project roles of this project.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createRole
      tags:
        - Authorization
      summary: Create a role
      description: >-
        Permission and delegation ceilings are enforced by the authorization service (grant_ceiling_exceeded). Composite
        roles (composite_role_ids, immutable after creation) must share the boundary type, and for organization and
        project roles the organization or project; they must not form a cycle, and the new role with every role it
        reaches must not exceed limits.max_role_expansion (422, AZ-011).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.write or org.roles.write by boundary (service-enforced, with delegation ceiling)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/roles/{role}:
    get:
      operationId: getRole
      tags:
        - Authorization
      summary: Get a role
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_role'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteRole
      tags:
        - Authorization
      summary: Delete a role
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.write or org.roles.write by boundary (service-enforced)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_role'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/roles/{role}/permissions:
    post:
      operationId: modifyRolePermissions
      tags:
        - Authorization
      summary: Change role permissions
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.write or org.roles.write by boundary (service-enforced, with delegation ceiling)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_role'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                add:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                remove:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/role-assignments:
    get:
      operationId: listRoleAssignments
      tags:
        - Authorization
      summary: List role assignments
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: subject_id
          in: query
          required: false
          schema:
            type: string
          description: Subject filter.
        - name: subject_type
          in: query
          required: false
          schema:
            type: string
          description: Subject type (default user when subject_id is set).
        - name: scope_id
          in: query
          required: false
          schema:
            type: string
          description: Scope filter.
        - name: scope_type
          in: query
          required: false
          schema:
            type: string
          description: Scope type.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RoleAssignment'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: assignRole
      tags:
        - Authorization
      summary: Assign a role
      description: >-
        scope defaults to the realm; a realm scope must name this realm. Answers 202 pending_approval (a role-assignment
        request another administrator approves) when the role requires approval, or when the subject is an agent service
        principal and the role is privileged (MCH-017): realm-boundary, owner, wildcard or any permission registered as
        privileged, through composition at any depth.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.assign or org.roles.assign by scope (service-enforced, with grant ceiling)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role_id:
                  type: string
                subject:
                  $ref: '#/components/schemas/AuthzSubject'
                scope:
                  $ref: '#/components/schemas/AuthzScope'
                expires_at:
                  type:
                    - string
                    - 'null'
                  format: date-time
                valid_from:
                  type:
                    - string
                    - 'null'
                  format: date-time
                conditions:
                  $ref: '#/components/schemas/GrantConditions'
                reason:
                  type: string
              required:
                - role_id
                - subject
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleAssignment'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/role-assignments/{assignment}:
    delete:
      operationId: unassignRole
      tags:
        - Authorization
      summary: Remove a role assignment
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.assign or org.roles.assign by scope (service-enforced)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_assignment'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/subjects/{subject}/permissions:
    get:
      operationId: getSubjectPermissions
      tags:
        - Authorization
      summary: Inspect a subject's effective permissions
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_subject'
        - $ref: '#/components/parameters/RequestId'
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
          description: Evaluate in this organization.
        - name: project_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Evaluate for a resource of this project: the subject's project-scoped role assignments for it count too
            (AZ-002). The project must exist and, with organization_id, belong to that organization (owned, or shared
            through an active project grant); otherwise 422.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EffectivePermissions'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/authorization/check:
    post:
      operationId: checkAuthorization
      tags:
        - Authorization
      summary: Evaluate one authorization decision
      description: >-
        Requires realm.authorization.check. Deny by default on malformed input; obligations are mandatory conditions.
        subject_token evaluation requires a service-principal caller registered as introspector for the token audience.
        With resource.project_id the subject's role assignments scoped to that project are evaluated in addition to
        realm and organization ones (AZ-002); an unknown project denies with UNKNOWN_PROJECT, and a project that does
        not belong to the decision's organization (resource.org_id or the token's) with PROJECT_ORGANIZATION_MISMATCH.
      security:
        - adminToken: []
      x-trust-class: resource-server
      x-permissions:
        - realm.authorization.check
        - realm.authorization.simulate (free-form subject)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionRequest'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Decision'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/authorization/check-batch:
    post:
      operationId: checkAuthorizationBatch
      tags:
        - Authorization
      summary: Evaluate a bounded batch of decisions
      security:
        - adminToken: []
      x-trust-class: resource-server
      x-permissions:
        - realm.authorization.check
        - realm.authorization.simulate (free-form subject)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                checks:
                  type: array
                  items:
                    $ref: '#/components/schemas/DecisionRequest'
                  minItems: 1
                  description: 1..limits.max_batch_size checks.
              required:
                - checks
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  decisions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Decision'
                required:
                  - decisions
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/service-principals:
    get:
      operationId: listServicePrincipals
      tags:
        - Machine identities
      summary: List service principals
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.service_principals.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServicePrincipal'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createServicePrincipal
      tags:
        - Machine identities
      summary: Create a service principal
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.service_principals.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServicePrincipalInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrincipal'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/service-principals/{id}:
    get:
      operationId: getServicePrincipal
      tags:
        - Machine identities
      summary: Get a service principal
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.service_principals.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrincipal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: updateServicePrincipal
      tags:
        - Machine identities
      summary: Update a service principal
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.service_principals.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchOptional'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServicePrincipalInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrincipal'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteServicePrincipal
      tags:
        - Machine identities
      summary: Delete a service principal
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.service_principals.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/service-principals/{id}/disable:
    post:
      operationId: disableServicePrincipal
      tags:
        - Machine identities
      summary: Disable a service principal
      description: Any request body is ignored.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.service_principals.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/service-principals/{id}/enable:
    post:
      operationId: enableServicePrincipal
      tags:
        - Machine identities
      summary: Enable a service principal
      description: Any request body is ignored.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.service_principals.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/api-keys:
    get:
      operationId: listAPIKeys
      tags:
        - Machine identities
      summary: List API keys and personal tokens
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.api_keys.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: owner_type
          in: query
          required: false
          schema:
            type: string
          description: service_principal or user.
        - name: owner_id
          in: query
          required: false
          schema:
            type: string
          description: Owner identifier.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/MachineCredential'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createAPIKey
      tags:
        - Machine identities
      summary: Create an API key for a service principal
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.api_keys.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                audience:
                  type: string
                name:
                  type: string
                organization_id:
                  type: string
                scopes:
                  items:
                    type: string
                  type:
                    - array
                    - 'null'
                ttl_days:
                  type: integer
                  maximum: 365
                  description: Expiry is mandatory; at most 365 days.
                service_principal_id:
                  type: string
              type: object
              required:
                - audience
                - name
                - scopes
                - service_principal_id
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_key:
                    type: string
                    x-secret: true
                    description: >-
                      API key (pa_key_ prefix). Returned exactly once; it is never stored in plaintext, never shown
                      again and never replayed from the idempotency store.
                  credential:
                    $ref: '#/components/schemas/MachineCredential'
                  notice:
                    type: string
                required:
                  - api_key
                  - credential
                  - notice
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/api-keys/{id}:
    delete:
      operationId: revokeAPIKey
      tags:
        - Machine identities
      summary: Revoke an API key or personal token
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.api_keys.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/credential-inventory:
    get:
      operationId: getCredentialInventory
      tags:
        - Machine identities
      summary: Credential inventory with hygiene flags
      description: Flags credentials expiring within 14 days or unused for 60 days.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.credentials.inventory
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CredentialInventoryItem'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/settings:
    get:
      operationId: getRealmSettings
      tags:
        - Realm
      summary: Get realm settings
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealmSettings'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      operationId: replaceRealmPolicy
      tags:
        - Realm
      summary: Replace the realm policy
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchRequired'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                policy:
                  $ref: '#/components/schemas/RealmPolicy'
                reason:
                  type: string
              required:
                - policy
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                type: object
                properties:
                  policy:
                    $ref: '#/components/schemas/RealmPolicy'
                  policy_revision:
                    type: integer
                    format: int64
                  version:
                    type: integer
                    format: int64
                required:
                  - policy
                  - policy_revision
                  - version
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/emergency/realm-state:
    post:
      operationId: setRealmEmergencyState
      tags:
        - Realm
      summary: Suspend or reactivate the realm (emergency)
      security:
        - adminToken: []
      x-trust-class: operator-only
      x-permissions:
        - realm.emergency
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                state:
                  type: string
                  enum:
                    - active
                    - suspended
                reason:
                  type: string
              required:
                - state
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    enum:
                      - active
                      - suspended
                required:
                  - state
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/signing-keys:
    get:
      operationId: listSigningKeys
      tags:
        - Realm
      summary: List signing key lifecycle metadata
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.keys.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SigningKeyMetadata'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/signing-key-rotations:
    post:
      operationId: rotateSigningKey
      tags:
        - Realm
      summary: Rotate the realm signing key
      description: Requires realm.keys.rotate and authentication within the last 5 minutes.
      security:
        - adminToken: []
      x-trust-class: operator-only
      x-permissions:
        - realm.keys.rotate
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected. The body may
          be empty (treated as {}), but Content-Type: application/json is still required.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum:
                    - planned
                    - emergency
                  description: Anything other than emergency is treated as planned.
                algorithm:
                  type: string
                  description: Defaults to keys.signing_algorithm.
                reason:
                  type: string
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  kid:
                    type: string
                  mode:
                    type: string
                    enum:
                      - planned
                      - emergency
                required:
                  - kid
                  - mode
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/audit-events:
    get:
      operationId: listAuditEvents
      tags:
        - Audit
      summary: Query audit events
      description: >-
        Filters combine with AND. Type prefixes are literal, including underscores, percent and backslash. Keep filters
        while following next_cursor; only limit may change. A cursor from another route, organization or filter set
        returns 400.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.audit.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
          description: Restrict to one organization.
        - name: id
          in: query
          required: false
          schema:
            type: string
          description: One event by ID (evt_...), for example the audit_event_id of a security.alert.
        - name: actor_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by actor.
        - name: subject_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by subject.
        - name: type
          in: query
          required: false
          schema:
            type: string
          description: Exact event type.
        - name: type_prefix
          in: query
          required: false
          schema:
            type: string
          description: Literal event type prefix; percent, underscore and backslash have no wildcard or escape meaning.
        - name: outcome
          in: query
          required: false
          schema:
            type: string
          description: success, denied or failure.
        - name: client_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by client.
        - name: request_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by request ID.
        - name: impersonation_grant_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by support grant.
        - name: grant_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by authorization grant.
        - name: session_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by session (the event session or the acting session).
        - name: target_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by target object ID.
        - name: category
          in: query
          required: false
          schema:
            type: string
          description: Filter by audit category (security, configuration, operations, emergency, ...).
        - name: network
          in: query
          required: false
          schema:
            type: string
          description: IP address or CIDR prefix; matches events whose stored, truncated network context overlaps it (AUD-011).
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: RFC 3339 lower bound.
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: RFC 3339 upper bound.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditEvent'
                  next_cursor:
                    type: string
                    description: >-
                      Opaque cursor for the next page; an empty string when there are no more results. Cursors are bound
                      to the realm and listing and cannot be replayed elsewhere.
                required:
                  - items
                  - next_cursor
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/audit-integrity:
    get:
      operationId: verifyAuditIntegrity
      tags:
        - Audit
      summary: Verify the audit hash chain
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.audit.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditVerificationReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/audit-exports:
    post:
      operationId: exportAuditEvents
      tags:
        - Audit
      summary: Export audit evidence (asynchronous)
      description: Users need recent authentication.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.audit.export
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected. The body may
          be empty (treated as {}), but Content-Type: application/json is still required.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                organization_id:
                  type: string
                from:
                  type: string
                  description: RFC 3339 lower bound.
                to:
                  type: string
                  description: RFC 3339 upper bound.
                impersonation_grant_id:
                  type: string
                  description: Export only the evidence of one support grant (IMP-024).
              additionalProperties: false
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/jobs/{id}:
    get:
      operationId: getJob
      tags:
        - Jobs
      summary: Inspect a job
      description: Visible to the requester or holders of realm.jobs.read; otherwise 404.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - requester
        - realm.jobs.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/jobs/{id}/cancel:
    post:
      operationId: cancelJob
      tags:
        - Jobs
      summary: Cancel a job
      description: Organization deletions cannot be cancelled (409). Any request body is ignored.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - requester
        - realm.jobs.cancel
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/jobs/{id}/downloads:
    post:
      operationId: issueJobDownload
      tags:
        - Jobs
      summary: Issue a download token for a protected job result
      description: Only the requester; users need recent authentication. Any request body is ignored.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - requester
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  download_token:
                    type: string
                    x-secret: true
                    description: >-
                      Single-use download credential valid for 300 seconds. Returned exactly once; it is never stored in
                      plaintext, never shown again and never replayed from the idempotency store.
                  expires_in:
                    type: integer
                    const: 300
                required:
                  - download_token
                  - expires_in
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/job-downloads:
    post:
      operationId: downloadJobResult
      tags:
        - Jobs
      summary: Download a protected job result
      description: >-
        Consumes the download token. The requester must still hold the permission the job needed (for example
        realm.data.export for a realm export) when the token is redeemed; a refusal does not consume the token.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - requester
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                download_token:
                  type: string
                  x-secret: true
              required:
                - download_token
              additionalProperties: false
      responses:
        '200':
          description: >-
            The decrypted job result. Audit and realm data exports are NDJSON (application/x-ndjson, filename
            export.ndjson); other results are one JSON document (application/json, filename export.json).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Content-Disposition:
              schema:
                type: string
              description: attachment; filename="export.json" or filename="export.ndjson"
          content:
            application/json:
              schema: {}
            application/x-ndjson:
              schema:
                type: string
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/impersonation-requests:
    post:
      operationId: requestSupportAccess
      tags:
        - Support access
      summary: Request support access
      description: Human operators only.
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImpersonationRequestInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImpersonationRequest'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/impersonation-requests/{id}/approve:
    post:
      operationId: approveSupportAccess
      tags:
        - Support access
      summary: Approve support access
      description: Independent eligible approver (user) required. Any request body is ignored.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/impersonation-requests/{id}/issue:
    post:
      operationId: issueSupportAccess
      tags:
        - Support access
      summary: Issue an approved support grant
      description: Human operators only. Any request body is ignored.
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImpersonationIssued'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/impersonation-grants:
    get:
      operationId: listSupportGrants
      tags:
        - Support access
      summary: List support grants
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - support.impersonation.read (otherwise only the caller's own grants)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - name: ticket_reference
          in: query
          required: false
          schema:
            type: string
          description: Only grants whose request carried this ticket reference (IMP-023).
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: actor_user_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by operator (forced to the caller without support.impersonation.read).
        - name: target_user_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by target user.
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by organization.
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: Filter by state.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ImpersonationGrant'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/impersonation-grants/{id}/revoke:
    post:
      operationId: revokeSupportGrant
      tags:
        - Support access
      summary: End a support grant
      description: 'Note: the body is decoded leniently (decode errors are ignored).'
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: >-
          Optional JSON body. This handler ignores decoding errors, so malformed or unknown members are silently
          dropped.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/impersonation-grants/{id}/handoffs:
    post:
      operationId: createSupportHandoff
      tags:
        - Support access
      summary: Create a destination-bound support entry code
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                destination_client_id:
                  type: string
              required:
                - destination_client_id
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  handoff_code:
                    type: string
                    x-secret: true
                    description: >-
                      Single-use handoff code for the destination backend. Returned exactly once; it is never stored in
                      plaintext, never shown again and never replayed from the idempotency store.
                  expires_at:
                    type: string
                    format: date-time
                required:
                  - handoff_code
                  - expires_at
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/impersonation-handoffs/redeem:
    post:
      operationId: redeemSupportHandoff
      tags:
        - Support access
      summary: Redeem a support entry code
      description: >-
        Called by the registered destination backend (confidential client). Public clients are rejected (401). Errors
        use problem details.
      security:
        - clientSecretBasic: []
        - {}
      x-trust-class: resource-server
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: Client identifier (client_secret_post, private_key_jwt or public clients).
                client_secret:
                  type: string
                  format: password
                  description: client_secret_post credential. Prefer client_secret_basic.
                client_assertion_type:
                  type: string
                  const: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                client_assertion:
                  type: string
                  description: private_key_jwt assertion (audience is the endpoint URL).
                handoff_code:
                  type: string
                  x-secret: true
              required:
                - handoff_code
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImpersonationIssued'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/webhooks:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List webhook subscriptions
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.webhooks.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by organization.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSubscription'
                  event_types:
                    type: array
                    items:
                      type: string
                    description: Subscribable event types.
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create a webhook subscription
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.webhooks.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscription:
                    $ref: '#/components/schemas/WebhookSubscription'
                  signing_secret:
                    type: string
                    x-secret: true
                    description: >-
                      Webhook signing secret. Returned exactly once; it is never stored in plaintext, never shown again
                      and never replayed from the idempotency store.
                  notice:
                    type: string
                required:
                  - subscription
                  - signing_secret
                  - notice
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/webhooks/{id}:
    get:
      operationId: getWebhook
      tags:
        - Webhooks
      summary: Get a webhook subscription
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.webhooks.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: updateWebhook
      tags:
        - Webhooks
      summary: Update a webhook subscription
      description: >-
        Partial update: absent fields keep their current values. A state-only change (pause, resume, disable) does not
        re-resolve the destination. The organization of a subscription cannot change.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.webhooks.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchOptional'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                allow_private_network:
                  type: boolean
                destination_url:
                  type: string
                  format: uri
                  description: HTTPS destination subject to the operator egress policy.
                event_types:
                  items:
                    type: string
                  type:
                    - array
                    - 'null'
                  minItems: 1
                  description: Event types from the catalog in api/events (also returned by GET /webhooks as event_types).
                name:
                  type: string
                event_version:
                  type: integer
                  enum:
                    - 1
                    - 2
                  description: Event schema version (EXT-018).
                payload_form:
                  type: string
                  enum:
                    - minimal
                    - standard
                state:
                  type: string
                  enum:
                    - active
                    - paused
                    - disabled
              type: object
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete a webhook subscription
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.webhooks.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/webhooks/{id}/rotate-secret:
    post:
      operationId: rotateWebhookSecret
      tags:
        - Webhooks
      summary: Rotate the signing secret
      description: The previous secret remains valid (dual signatures) for 24 hours. Any request body is ignored.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.webhooks.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  signing_secret:
                    type: string
                    x-secret: true
                    description: >-
                      New webhook signing secret. Returned exactly once; it is never stored in plaintext, never shown
                      again and never replayed from the idempotency store.
                  previous_secret_valid_for_seconds:
                    type: integer
                    const: 86400
                required:
                  - signing_secret
                  - previous_secret_valid_for_seconds
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/webhooks/{id}/deliveries:
    get:
      operationId: listWebhookDeliveries
      tags:
        - Webhooks
      summary: Delivery history
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.webhooks.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookDelivery'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/webhooks/{id}/deliveries/{delivery}/replay:
    post:
      operationId: replayWebhookDelivery
      tags:
        - Webhooks
      summary: Retry a delivery
      description: Redelivers with the stable original event ID. Any request body is ignored.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.webhooks.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_delivery'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/user-imports:
    post:
      operationId: importUsers
      tags:
        - Imports and exports
      summary: Start a bulk user import (asynchronous)
      description: Creates a user.import job. The Idempotency-Key is also bound to the job.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.import
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type: string
                  default: proudauth.user-import.v1
                  description: >-
                    The records format (MIG-002); an unsupported format is refused with 422. GET /user-import-formats
                    lists the formats.
                source_system:
                  type: string
                  minLength: 1
                users:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
                  minItems: 1
                  maxItems: 1000
                  description: User records; see api/schemas/user-import.schema.json.
                dry_run:
                  type: boolean
                trust_email_verification:
                  type: boolean
                verification_reason:
                  type: string
                  minLength: 10
                  description: >-
                    Required with trust_email_verification, which also requires realm.users.verification.override
                    (USR-005).
                allow_owner_roles:
                  type: boolean
                import_totp:
                  type: boolean
                  description: >-
                    Authorizes importing totp_secret seeds (MIG-007). Requires realm.users.credentials.manage and an MFA
                    session; without it, a record carrying totp_secret fails. Seeds are base32 (80 to 512 bits),
                    re-encrypted under this deployment's keys and audited as mfa.totp.imported.
              required:
                - source_system
                - users
              additionalProperties: false
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                  dry_run:
                    type: boolean
                required:
                  - job_id
                  - dry_run
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/configuration/exports:
    post:
      operationId: exportConfiguration
      tags:
        - Configuration
      summary: Export realm configuration (asynchronous)
      description: Creates a config.export job. Any request body is ignored.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.configuration.export
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/configuration/validate:
    post:
      operationId: validateConfiguration
      tags:
        - Configuration
      summary: Validate a configuration document
      description: >-
        No mutation. Requires realm.configuration.import. Returns the plan the import would act on, with status 200 even
        when it lists errors: besides validation errors it reports a policy change without expected_policy_revision and
        every change the caller lacks the authority for through the API (realm.settings.write, realm.clients.write,
        realm.resources.write, realm.roles.write), so a plan never shows as valid what the import would refuse.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.configuration.import
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - name: mode
          in: query
          required: false
          schema:
            type: string
            enum:
              - reconcile
          description: >-
            reconcile (SDK-012): existing clients, resources and role permissions that differ from the document are
            planned as updates and applied (never deleted); without it they are reported as drift only.
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigDocument'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigPlan'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/configuration/imports:
    post:
      operationId: importConfiguration
      tags:
        - Configuration
      summary: Reconcile a configuration document
      description: >-
        Creates missing objects; existing objects are reported unchanged, or with ?mode=reconcile existing clients,
        resources and role permissions that differ are updated (never deleted; resource members the document omits keep
        their values); a client whose client_type differs and that would be updated is a plan error (a type never
        changes). Every change needs the authority it needs through the API (realm.settings.write, realm.clients.write,
        realm.resources.write, realm.roles.write): an import without it is refused with 403, and ?dry_run=true reports
        it in the plan (422). A policy change needs expected_policy_revision. Users need recent authentication. The
        import is atomic: every change commits or none does.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.configuration.import
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - name: mode
          in: query
          required: false
          schema:
            type: string
            enum:
              - reconcile
          description: >-
            reconcile (SDK-012): existing clients, resources and role permissions that differ from the document are
            planned as updates and applied (never deleted); without it they are reported as drift only.
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: dry_run
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: With true, only the plan is returned.
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigDocument'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: Applied
                    properties:
                      plan:
                        $ref: '#/components/schemas/ConfigPlan'
                      applied:
                        type:
                          - array
                          - 'null'
                        items:
                          type: string
                    required:
                      - plan
                      - applied
                  - $ref: '#/components/schemas/ConfigPlan'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          description: >-
            The plan contains errors; nothing was applied. The body is the ConfigPlan (application/json), not a problem
            document, unless request decoding failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigPlan'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/notification-settings:
    get:
      operationId: getNotificationSettings
      tags:
        - Notifications
      summary: Get delivery settings
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.notifications.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            An organization's sender settings instead of the realm's; the ETag then covers them (for PATCH with
            organization_id).
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  sender_address:
                    type:
                      - string
                      - 'null'
                  sender_name:
                    type:
                      - string
                      - 'null'
                  reply_to:
                    type:
                      - string
                      - 'null'
                  default_locale:
                    type:
                      - string
                      - 'null'
                  adapter:
                    type: string
                required:
                  - sender_address
                  - sender_name
                  - reply_to
                  - default_locale
                  - adapter
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: updateNotificationSettings
      tags:
        - Notifications
      summary: Update delivery settings
      description: 'Note: despite PATCH, every field is written (omitted fields are cleared; default_locale falls back to en).'
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.notifications.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sender_address:
                  type: string
                sender_name:
                  type: string
                reply_to:
                  type: string
                default_locale:
                  type: string
                organization_id:
                  type: string
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/templates:
    get:
      operationId: listTemplates
      tags:
        - Notifications
      summary: List active templates
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.notifications.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotificationTemplate'
                  variables:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: Template event type -> allowed variables.
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: upsertTemplate
      tags:
        - Notifications
      summary: Create or replace a template
      description: Disables the previous active template for the same organization, event type and locale.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.notifications.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organization_id:
                  type: string
                event_type:
                  type: string
                locale:
                  type: string
                  description: Defaults to en.
                subject:
                  type: string
                body_text:
                  type: string
                body_html:
                  type: string
              required:
                - event_type
                - subject
                - body_text
              additionalProperties: false
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                required:
                  - id
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/templates/{id}:
    delete:
      operationId: disableTemplate
      tags:
        - Notifications
      summary: Disable a template
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.notifications.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/notification-tests:
    post:
      operationId: sendNotificationTest
      tags:
        - Notifications
      summary: Send a test message to the caller's verified email
      description: Any request body is ignored.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.notifications.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                  note:
                    type: string
                required:
                  - job_id
                  - note
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/notification-jobs:
    get:
      operationId: listNotificationJobs
      tags:
        - Notifications
      summary: List notification jobs
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.notifications.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: reference_type
          in: query
          required: false
          schema:
            type: string
          description: Filter by reference type.
        - name: reference_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by reference ID.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotificationJob'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /health/live:
    get:
      operationId: live
      tags:
        - Health
      summary: Process liveness
      description: >-
        Never touches dependencies. Health probes draw on the reserved administrative request pool, so 503 indicates
        severe overload.
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: ok
                required:
                  - status
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /health/ready:
    get:
      operationId: ready
      tags:
        - Health
      summary: Readiness
      description: Checks the database, schema version and signing-key availability. Discloses no configuration details.
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: ready
                required:
                  - status
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: Database unavailable, schema behind, or an active realm has no usable signing key.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - unavailable
                      - degraded
                required:
                  - status
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api/v1/realms/{realm}/policies:
    get:
      operationId: listPolicies
      tags:
        - Authorization
      summary: List authorization policies
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createPolicy
      tags:
        - Authorization
      summary: Create a policy with its first staged revision
      description: >-
        Policies are typed, bounded restrictions evaluated after RBAC: they can deny or add obligations but never grant
        (AZ-013, AZ-015). Missing attributes fail closed.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyCreate'
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  policy:
                    $ref: '#/components/schemas/Policy'
                  version:
                    $ref: '#/components/schemas/PolicyVersion'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/policies/{policy}:
    get:
      operationId: getPolicy
      tags:
        - Authorization
      summary: Get a policy
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_policy'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/policies/{policy}/versions:
    get:
      operationId: listPolicyVersions
      tags:
        - Authorization
      summary: List immutable policy revisions
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_policy'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PolicyVersion'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: stagePolicyVersion
      tags:
        - Authorization
      summary: Stage a new revision
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_policy'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                definition:
                  $ref: '#/components/schemas/PolicyDefinition'
                note:
                  type: string
                  maxLength: 500
              required:
                - definition
              additionalProperties: false
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyVersion'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/policies/{policy}/versions/{version}:
    get:
      operationId: getPolicyVersion
      tags:
        - Authorization
      summary: Get one revision
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_policy'
        - $ref: '#/components/parameters/Path_version'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyVersion'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/policies/{policy}/versions/{version}/approve:
    post:
      operationId: approvePolicyVersion
      tags:
        - Authorization
      summary: Approve a staged revision
      description: The author cannot approve their own revision (AZ-018). Requires recent authentication.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.publish
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_policy'
        - $ref: '#/components/parameters/Path_version'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyVersion'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/policies/{policy}/versions/{version}/publish:
    post:
      operationId: publishPolicyVersion
      tags:
        - Authorization
      summary: Publish a revision
      description: >-
        Policies with requires_approval publish only independently approved revisions. Other nodes observe the change
        within 5 seconds (AZ-019).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.publish
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_policy'
        - $ref: '#/components/parameters/Path_version'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/policies/{policy}/rollback:
    post:
      operationId: rollbackPolicy
      tags:
        - Authorization
      summary: Restore a previously published revision
      description: Creates and publishes a new revision with the old content; history is never rewritten (AZ-017).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.publish
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_policy'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to_version:
                  type: integer
                  minimum: 1
              required:
                - to_version
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/policies/{policy}/state:
    post:
      operationId: setPolicyState
      tags:
        - Authorization
      summary: Enable or disable evaluation
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.publish
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_policy'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                state:
                  type: string
                  enum:
                    - active
                    - disabled
              required:
                - state
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/policies/{policy}/diff:
    get:
      operationId: diffPolicyVersions
      tags:
        - Authorization
      summary: Human-readable diff between revisions
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_policy'
        - $ref: '#/components/parameters/RequestId'
        - name: from
          in: query
          required: true
          schema:
            type: integer
        - name: to
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  from:
                    type: integer
                  to:
                    type: integer
                  diff:
                    type: string
                    description: Line diff of the canonical definitions ("+ " added, "- " removed).
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/authorization/simulate:
    post:
      operationId: simulateAuthorization
      tags:
        - Authorization
      summary: Simulate decisions against a candidate policy revision
      description: >-
        Evaluates each check with the active policies and, when a candidate is given, with the candidate in place of the
        policy active revision. Simulations are not audited as decisions.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.authorization.simulate
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                policy:
                  type: string
                  description: Policy ID or name whose active revision the candidate replaces.
                version:
                  type: integer
                  description: Revision to simulate (when no definition is given).
                definition:
                  $ref: '#/components/schemas/PolicyDefinition'
                checks:
                  type: array
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/DecisionRequest'
              required:
                - checks
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        current:
                          $ref: '#/components/schemas/Decision'
                        candidate:
                          $ref: '#/components/schemas/Decision'
                        changed:
                          type: boolean
                  changed:
                    type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/me/remembered-devices:
    get:
      operationId: listRememberedDevices
      tags:
        - Self-service
      summary: List remembered devices
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RememberedDevice'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: revokeAllRememberedDevices
      tags:
        - Self-service
      summary: Forget every remembered device
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  revoked:
                    type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/remembered-devices/{id}:
    delete:
      operationId: revokeRememberedDevice
      tags:
        - Self-service
      summary: Forget one remembered device
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/auth/transactions/{id}/remember-device:
    post:
      operationId: rememberDeviceStep
      tags:
        - Interaction
      summary: Opt in to remembering this device
      description: >-
        After a genuine second factor completes the transaction, a remembered-device secret is issued: browsers receive
        it as the HttpOnly pa_rd cookie, headless callers in one_time.remembered_device_token, to send later as
        X-Remembered-Device. It skips the MFA prompt only where realm policy allows and never raises assurance
        (AUT-013).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                remember:
                  type: boolean
              required:
                - remember
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/role-assignment-requests:
    get:
      operationId: listRoleAssignmentRequests
      tags:
        - Authorization
      summary: List role assignment approval requests
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AssignmentRequest'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/role-assignment-requests/{id}/approve:
    post:
      operationId: approveRoleAssignmentRequest
      tags:
        - Authorization
      summary: Approve a role assignment request
      description: >-
        The approver is the authenticated caller; requester and subject cannot approve, and the approver must be able to
        grant the role (AZ-018). Requires recent authentication.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - authority to grant the role (checked by the authorization service)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentRequest'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/role-assignment-requests/{id}/reject:
    post:
      operationId: rejectRoleAssignmentRequest
      tags:
        - Authorization
      summary: Reject a role assignment request
      description: >-
        The approver is the authenticated caller; requester and subject cannot approve, and the approver must be able to
        grant the role (AZ-018). Requires recent authentication.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - authority to grant the role (checked by the authorization service)
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentRequest'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/role-assignment-requests/{id}/approve:
    post:
      operationId: approveRoleAssignmentRequestOrg
      tags:
        - Authorization
      summary: Approve a role assignment request
      description: >-
        The approver is the authenticated caller; requester and subject cannot approve, and the approver must be able to
        grant the role (AZ-018). Requires recent authentication.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.roles.assign
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentRequest'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/role-assignment-requests/{id}/reject:
    post:
      operationId: rejectRoleAssignmentRequestOrg
      tags:
        - Authorization
      summary: Reject a role assignment request
      description: >-
        The approver is the authenticated caller; requester and subject cannot approve, and the approver must be able to
        grant the role (AZ-018). Requires recent authentication.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.roles.assign
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentRequest'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/auth/transactions/{id}/account:
    post:
      operationId: selectAccountStep
      tags:
        - Interaction
      summary: Answer prompt=select_account
      description: Offered as the select_account action when prompt=select_account meets an existing SSO session (OIDC-005).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                continue:
                  type: boolean
                  description: true keeps the signed-in account; false switches to signing in as someone else.
              required:
                - continue
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/auth/transactions/{id}/transient:
    post:
      operationId: transientSessionStep
      tags:
        - Interaction
      summary: Request a transient session
      description: >-
        A transient session lasts at most one hour, uses a browser-session cookie and never yields refresh tokens
        (SES-020).
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transient:
                  type: boolean
              required:
                - transient
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/session-events:
    get:
      operationId: readSessionEvents
      tags:
        - Events
      summary: Read the session and access change stream
      description: >-
        At-least-once, gap-free stream ordered by commit horizon: events of still-open transactions are withheld, so an
        advancing cursor never skips a later-committing event (SES-019). Types: session.revoked,
        user.suspended/locked/deleted/password_reset/recovery_restricted, security.refresh_reuse_detected,
        security.credential_compromised, organization.membership.removed/suspended, organization.suspended/deleted,
        authorization.role.unassigned, support.impersonation.ended, client.state_changed, signing_key.rotated. History
        is retained 7 days after dispatch; a cursor followed by events that were pruned returns 410 cursor_expired (a
        caught-up cursor on a quiet realm stays valid), and the consumer resynchronizes by reading the retained history
        from its beginning (no cursor).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.session_events.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Position from a previous next_cursor (empty = beginning of retained history).
        - name: from
          in: query
          required: false
          schema:
            type: string
            enum:
              - now
          description: Return only the current head position, to start following from now.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
        - name: wait
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 25
          description: Long-poll seconds when no events are available.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                      properties:
                        event_id:
                          type: string
                        event_type:
                          type: string
                        occurred_at:
                          type: string
                          format: date-time
                        organization_id:
                          type: string
                        data:
                          type: object
                          description: Identifiers and states only.
                        cursor:
                          type: string
                  next_cursor:
                    type: string
                required:
                  - events
                  - next_cursor
        '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'
        '410':
          $ref: '#/components/responses/Gone'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/hooks:
    get:
      operationId: listHooks
      tags:
        - Extensions
      summary: List pre-action hooks with health
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.hooks.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Hook'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createHook
      tags:
        - Extensions
      summary: Register a pre-action hook
      description: >-
        Pre-action hooks are signed (Webhook-Id/Timestamp/Signature), egress-controlled, time-bounded calls.
        Security-decision hooks always fail closed; only token.claims hooks may use failure_mode skip. Hooks cannot
        grant access, skip authentication or set reserved claims (EXT-009..EXT-012).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.hooks.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HookInput'
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  hook:
                    $ref: '#/components/schemas/Hook'
                  signing_secret:
                    type: string
                    x-secret: true
                    description: Returned once.
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/hooks/{id}:
    get:
      operationId: getHook
      tags:
        - Extensions
      summary: Get a hook
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.hooks.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hook'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateHook
      tags:
        - Extensions
      summary: Update a hook
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.hooks.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchRequired'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HookInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hook'
        '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/UnprocessableEntity'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteHook
      tags:
        - Extensions
      summary: Delete a hook
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.hooks.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/activity:
    get:
      operationId: getAccountActivity
      tags:
        - Self-service
      summary: Account activity summary
      description: >-
        Recent sign-ins, sessions, authenticator activity, security changes and support access for the caller (USR-019).
        Other principals are reported only by type; metadata is allowlisted. Query parameter days (1-365, default 30)
        bounds the window.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - name: days
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  since:
                    type: string
                    format: date-time
                  sign_ins:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityEvent'
                  sessions:
                    type: array
                    items:
                      type: object
                  authenticators:
                    type: array
                    items:
                      type: object
                  security_changes:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityEvent'
                  support_access:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityEvent'
                required:
                  - since
                  - sign_ins
                  - sessions
                  - authenticators
                  - security_changes
                  - support_access
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/invitations/batch:
    post:
      operationId: createInvitationBatch
      tags:
        - Invitations
      summary: Create invitations in bulk
      description: >-
        Validates and creates up to 100 invitations independently (INV-011). Each entry has its own result; one failure
        never rolls back the others; delivery is queued per invitation. Shared links are not accepted in batches.
        Retrying with the same Idempotency-Key replays the original results.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.invites.create
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/InvitationInput'
              required:
                - items
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  batch_id:
                    type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvitationBatchResult'
                required:
                  - batch_id
                  - results
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/invitations/{id}/reassign:
    post:
      operationId: reassignInvitation
      tags:
        - Invitations
      summary: Reassign a pending invitation to a new target
      description: >-
        Administrator-reviewed reassignment (INV-014): the pending invitation is revoked and superseded by a fresh
        invitation for the new address or account, re-validated against current roles, ceilings and domain policy.
        Requires org.invites.revoke as well and a review reason, which is audited.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.invites.create
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                user_id:
                  type: string
                reason:
                  type: string
                  minLength: 3
                  maxLength: 500
                locale:
                  type: string
              required:
                - reason
              additionalProperties: false
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  invitation:
                    $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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/projects/{project}/grants:
    get:
      operationId: listProjectGrants
      tags:
        - Projects
      summary: List project grants
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.projects.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_project'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectGrant'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createProjectGrant
      tags:
        - Projects
      summary: Delegate project roles to an organization
      description: >-
        Lets a non-owning organization invite users to the listed project roles (INV-012). allowed_role_ids is the
        organization ceiling for the project.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.projects.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_project'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organization_id:
                  type: string
                allowed_role_ids:
                  type: array
                  maxItems: 50
                  items:
                    type: string
                valid_until:
                  type: string
                  format: date-time
              required:
                - organization_id
              additionalProperties: false
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectGrant'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/projects/{project}/grants/{id}/revoke:
    post:
      operationId: revokeProjectGrant
      tags:
        - Projects
      summary: Revoke a project grant
      description: >-
        Revokes the grant and removes project role assignments made through it in the same transaction. Any request body
        is ignored.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.projects.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_project'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/sessions/{id}:
    delete:
      operationId: revokeUserSession
      tags:
        - Users
      summary: Revoke one session of a user
      description: >-
        Revokes a single session (SES-003) with its grants, refresh families and opaque tokens; back-channel logout is
        queued. Audited as session.revoked_by_admin.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.sessions.revoke
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/members/{membership}/permissions:
    get:
      operationId: inspectMemberPermissions
      tags:
        - Organizations
      summary: Inspect a member's effective permissions
      description: >-
        Scoped administrator inspection (AZ-009): the member's effective permissions in this organization with
        provenance. Realm-level grants are reported without role names; policy definitions are never included.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_membership'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EffectivePermissions'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/identity-providers:
    get:
      operationId: listOrganizationIdentityProviders
      tags:
        - Federation
      summary: List the organization's connections
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/IdentityProvider'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createOrganizationIdentityProvider
      tags:
        - Federation
      summary: Create an organization connection
      description: >-
        Organization-scoped federation connections managed by organization administrators (TEN-007). The connection is
        always scoped to the path organization; trusted-email linking is limited to the organization's verified domains;
        trust_upstream_mfa requires a realm administrator. Writes require an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProviderInput'
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/identity-providers/{id}:
    get:
      operationId: getOrganizationIdentityProvider
      tags:
        - Federation
      summary: Get an organization connection
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateOrganizationIdentityProvider
      tags:
        - Federation
      summary: Update an organization connection
      description: >-
        Organization-scoped federation connections managed by organization administrators (TEN-007). The connection is
        always scoped to the path organization; trusted-email linking is limited to the organization's verified domains;
        trust_upstream_mfa requires a realm administrator. Writes require an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchRequired'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProviderInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '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/UnprocessableEntity'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteOrganizationIdentityProvider
      tags:
        - Federation
      summary: Delete an organization connection
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/projects/{project}/ownership-transfer:
    post:
      operationId: transferProject
      tags:
        - Projects
      summary: Transfer project ownership
      description: >-
        Changes the accountable owner user and/or owning organization (APP-001) with an audited reason.
        owner_organization_id '-' clears the organization owner. Honors If-Match.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.projects.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_project'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                owner_user_id:
                  type: string
                owner_organization_id:
                  type: string
                reason:
                  type: string
                  minLength: 3
              required:
                - reason
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/projects/{project}/applications:
    get:
      operationId: listProjectApplications
      tags:
        - Projects
      summary: List a project's clients, resources and organization grants
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.projects.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_project'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  clients:
                    type: array
                    items:
                      type: object
                  resources:
                    type: array
                    items:
                      type: object
                  organization_grants:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectGrant'
                required:
                  - clients
                  - resources
                  - organization_grants
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/impersonation-requests/{id}/deny:
    post:
      operationId: denyImpersonationRequest
      tags:
        - Support
      summary: Deny or withdraw a support-access request
      description: >-
        Allowed for the requesting operator (withdraw) and for whoever may approve under the request policy: the
        customer, a second operator or an organization owner (IMP-022). Unrelated callers receive 404.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/impersonation-requests:
    get:
      operationId: listMyPendingSupportRequests
      tags:
        - Self-service
      summary: Support-access requests awaiting my approval
      description: >-
        Requests whose policy requires the customer's approval (IMP-022), with the stated reason and ticket. The
        operator is not identified.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        organization_id:
                          type: string
                        mode:
                          type: string
                        scopes:
                          type: array
                          items:
                            type: string
                        reason:
                          type: string
                        ticket_reference:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        expires_at:
                          type: string
                          format: date-time
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/credential-inventory/revocations:
    post:
      operationId: revokeInventoryCredentials
      tags:
        - Machines
      summary: Revoke credentials in bulk
      description: >-
        Revokes up to 100 API keys, personal tokens (akc_) and client secrets (ccr_) found in the inventory (MCH-016).
        Each is revoked in its own transaction with its own audit record; per-item permissions (realm.api_keys.manage,
        realm.clients.credentials) apply. Results are per item.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.credentials.inventory
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                reason:
                  type: string
                  minLength: 3
              required:
                - ids
                - reason
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: string
                          enum:
                            - revoked
                            - failed
                        error:
                          type: string
                  reason:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/notification-preferences:
    get:
      operationId: getNotificationPreferences
      tags:
        - Self-service
      summary: Optional notice preferences
      description: >-
        Only optional notices (currently new_login) can be muted; security and account notices are always delivered
        (MSG-010).
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  preferences:
                    type: object
                    additionalProperties:
                      type: boolean
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: setNotificationPreferences
      tags:
        - Self-service
      summary: Update optional notice preferences
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                preferences:
                  type: object
                  additionalProperties:
                    type: boolean
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  preferences:
                    type: object
                    additionalProperties:
                      type: boolean
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/delivery-events:
    post:
      operationId: recordDeliveryEvents
      tags:
        - Notifications
      summary: Provider delivery feedback
      description: >-
        Bounce and complaint callbacks from the email provider (MSG-007). Authenticated with a Standard Webhooks
        signature (Webhook-Id, Webhook-Timestamp, Webhook-Signature) over the raw body using
        delivery.email.events_secret; disabled (404) when no secret is configured. Permanent bounces and complaints
        suppress optional mail to the address; feedback never verifies or changes an identity.
      security: []
      x-trust-class: signed-provider-callback
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  type: array
                  minItems: 1
                  maxItems: 500
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - delivered
                          - bounce
                          - complaint
                      recipient:
                        type: string
                      provider_message_id:
                        type: string
                      permanent:
                        type: boolean
                    required:
                      - type
              required:
                - events
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  applied:
                    type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/notification-settings/check:
    post:
      operationId: checkNotificationDelivery
      tags:
        - Notifications
      summary: Check delivery configuration
      description: >-
        Connects to the configured SMTP server, negotiates TLS and authenticates without sending (MSG-012). Only the
        failing stage is returned; server responses and credentials go to the operator log.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.notifications.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  stage:
                    type: string
                    enum:
                      - ok
                      - connect
                      - greeting
                      - starttls
                      - credentials
                      - authentication
                      - not_applicable
                  email_adapter:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/assisted-recoveries/{id}/approve:
    post:
      operationId: approveAssistedRecovery
      tags:
        - Users
      summary: Approve a scheduled assisted recovery
      description: >-
        Independent second-operator approval when the realm sets recovery.require_approval (MFA-009). Neither the
        requesting operator nor the account owner may approve.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - support.recovery.assist or realm.users.credentials.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/assisted-recoveries:
    get:
      operationId: listMyAssistedRecoveries
      tags:
        - Self-service
      summary: Scheduled assisted recoveries of my account
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/assisted-recoveries/{id}/cancel:
    post:
      operationId: cancelMyAssistedRecovery
      tags:
        - Self-service
      summary: Cancel a scheduled assisted recovery
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/registration-approvals:
    get:
      operationId: listRegistrationApprovals
      tags:
        - Users
      summary: List queued self-registrations
      description: >-
        Registrations queued by registration.require_approval (REG-008). Email addresses are masked. Filter with state
        (pending, approved, denied, expired).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.registrations.review
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        user_id:
                          type: string
                        email_hint:
                          type: string
                        state:
                          type: string
                        reviewer_id:
                          type: string
                        reason:
                          type: string
                        expires_at:
                          type: string
                          format: date-time
                        decided_at:
                          type: string
                          format: date-time
                        created_at:
                          type: string
                          format: date-time
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/registration-approvals/{id}/decision:
    post:
      operationId: decideRegistration
      tags:
        - Users
      summary: Approve or deny a queued registration
      description: >-
        Denial suspends the account. The applicant is notified; undecided reviews expire after 14 days and the account
        stays suspended.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.registrations.review
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                approve:
                  type: boolean
                reason:
                  type: string
              required:
                - approve
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/auth/transactions/{id}/guest:
    post:
      operationId: continueAsGuest
      tags:
        - Authentication
      summary: Continue as a guest
      description: >-
        Creates a low-privilege guest identity when registration.allow_guests is enabled (REG-010). Guests hold no
        organization membership or roles and are refused any context that requires MFA or an organization; assurance is
        urn:proudauth:acr:anonymous. Rate-limited like self-registration. Any request body is ignored.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/upgrade:
    post:
      operationId: upgradeGuest
      tags:
        - Self-service
      summary: Upgrade a guest account
      description: >-
        Sets a password and adds the email address unverified (REG-010). The account stops being a guest when the
        address is verified through POST /verification-challenges; the response is identical for addresses that already
        belong to another account, and verifying such an address fails, so nothing is linked or merged.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                password:
                  type: string
                  x-secret: true
              required:
                - email
                - password
              additionalProperties: false
      responses:
        '202':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  identifier_id:
                    type: string
                  next:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/merges:
    post:
      operationId: proposeAccountMerge
      tags:
        - Users
      summary: Propose merging an account into this one
      description: >-
        USR-011: records a reviewed plan and notifies both owners. Requires an MFA session. The account in the path
        survives.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source_user_id:
                  type: string
                reason:
                  type: string
                  minLength: 10
              required:
                - source_user_id
                - reason
              additionalProperties: false
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  survivor_id:
                    type: string
                  source_id:
                    type: string
                  reason:
                    type: string
                  plan:
                    type: object
                    description: >-
                      Reviewed effect: identifiers and federation links to move, organizations joined with the member
                      role only, source roles listed for review (never copied), credentials not transferred.
                  survivor_confirmed_at:
                    type: string
                    format: date-time
                  source_confirmed_at:
                    type: string
                    format: date-time
                  state:
                    type: string
                    enum:
                      - pending
                      - completed
                      - cancelled
                      - expired
                  expires_at:
                    type: string
                    format: date-time
                  created_at:
                    type: string
                    format: date-time
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/account-merges/{id}/execute:
    post:
      operationId: executeAccountMerge
      tags:
        - Users
      summary: Execute a confirmed merge
      description: >-
        Requires both owners' confirmation and an MFA session. Moves identifiers and federation links, joins
        organizations with the member role only, ends all sessions of both accounts, deletes the source as an alias of
        the survivor and publishes user.merged.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  survivor_id:
                    type: string
                  source_id:
                    type: string
                  reason:
                    type: string
                  plan:
                    type: object
                    description: >-
                      Reviewed effect: identifiers and federation links to move, organizations joined with the member
                      role only, source roles listed for review (never copied), credentials not transferred.
                  survivor_confirmed_at:
                    type: string
                    format: date-time
                  source_confirmed_at:
                    type: string
                    format: date-time
                  state:
                    type: string
                    enum:
                      - pending
                      - completed
                      - cancelled
                      - expired
                  expires_at:
                    type: string
                    format: date-time
                  created_at:
                    type: string
                    format: date-time
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/subject-aliases/{id}:
    get:
      operationId: getSubjectAlias
      tags:
        - Users
      summary: Resolve a merged-away subject
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  alias_id:
                    type: string
                  user_id:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/account-merges:
    get:
      operationId: listMyAccountMerges
      tags:
        - Self-service
      summary: Merges involving my account
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/account-merges/{id}/confirm:
    post:
      operationId: confirmAccountMerge
      tags:
        - Self-service
      summary: Confirm a merge of my account
      description: Requires recent authentication. Each account owner confirms separately.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/auth/transactions/{id}/registration:
    post:
      operationId: registerInTransaction
      tags:
        - Authentication
      summary: Register a new account in this transaction
      description: >-
        Browser form of POST /registrations (REG-001): the transaction cookie is scoped to this transaction's path, so
        login UIs register here with the same Origin and CSRF checks as every other step. The response is identical
        whether or not the address already belongs to an account.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                display_name:
                  type: string
                email:
                  type: string
                family_name:
                  type: string
                given_name:
                  type: string
                invitation:
                  type: string
                  x-secret: true
                  description: Invitation secret to accept during registration.
                locale:
                  type: string
                organization:
                  oneOf:
                    - $ref: '#/components/schemas/OrganizationInput'
                    - type: 'null'
                password:
                  type: string
                  format: password
                profile:
                  additionalProperties: {}
                  type:
                    - object
                    - 'null'
                terms_version:
                  type: string
                username:
                  type: string
              type: object
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/emergency/controls:
    get:
      operationId: getEmergencyControls
      tags:
        - Administration
      summary: List active emergency controls
      description: >-
        Grant classes switched off realm-wide and the clients, identity providers, organizations, service principals,
        hooks and webhooks currently disabled (SEC-020). Each list holds at most 200 IDs.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.emergency
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  realm_state:
                    type: string
                  disabled_grant_types:
                    type: array
                    items:
                      type: string
                  suspended_clients:
                    type: array
                    items:
                      type: string
                  disabled_identity_providers:
                    type: array
                    items:
                      type: string
                  suspended_organizations:
                    type: array
                    items:
                      type: string
                  disabled_service_principals:
                    type: array
                    items:
                      type: string
                  disabled_hooks:
                    type: array
                    items:
                      type: string
                  disabled_webhooks:
                    type: array
                    items:
                      type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: applyEmergencyControl
      tags:
        - Administration
      summary: Disable or re-enable a client, provider, organization, extension or grant class
      description: >-
        One audited emergency surface (SEC-020): the change takes effect at once, is recorded in the emergency audit
        category with the reason, and raises the emergency_action security signal. A disabled grant class is refused at
        the authorization, device authorization and token endpoints (unauthorized_client) and no refresh tokens are
        minted while refresh_token is disabled; the operator CLI client (proudauth-cli) is exempt so the control can
        always be reversed. Disabling a client suspends it and revokes its grants; disabling an organization suspends
        it. Signing keys use emergency rotation instead.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.emergency
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - target_type
                - target_id
                - action
                - reason
              properties:
                target_type:
                  type: string
                  enum:
                    - grant_type
                    - client
                    - identity_provider
                    - organization
                    - service_principal
                    - hook
                    - webhook
                target_id:
                  type: string
                  description: >-
                    The object ID, or for grant_type one of authorization_code, refresh_token, client_credentials,
                    urn:ietf:params:oauth:grant-type:device_code, urn:ietf:params:oauth:grant-type:token-exchange.
                action:
                  type: string
                  enum:
                    - disable
                    - enable
                reason:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  target_type:
                    type: string
                  target_id:
                    type: string
                  state:
                    type: string
                    enum:
                      - disabled
                      - enabled
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/account-merges/{id}/cancel:
    post:
      operationId: cancelAccountMerge
      tags:
        - Users
      summary: Cancel a pending merge
      description: >-
        Withdraws a pending proposal (user.merge.cancelled). Lapsed proposals expire on their own and never block a new
        proposal for the same account.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/account-merges/{id}/decline:
    post:
      operationId: declineAccountMerge
      tags:
        - Self-service
      summary: Decline a merge of my account
      description: >-
        Either account owner can decline a pending merge (user.merge.declined); the administrator may propose again
        later.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/lifecycle/preview:
    get:
      operationId: previewUserLifecycle
      tags:
        - Users
      summary: Preview account lifecycle jobs (dry run)
      description: >-
        What the next lifecycle run would do (USR-015): abandoned unverified registrations and unused guests are
        deleted, dormant accounts are reported or suspended per lifecycle.dormant_action, and scheduled deactivations
        suspend the account. Shows the number due and up to 20 sample account IDs per rule; nothing changes. The worker
        applies at most batch_size accounts per rule per run, re-checking each one.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  dry_run:
                    type: boolean
                  batch_size:
                    type: integer
                  rules:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          enum:
                            - unverified_expired
                            - dormant
                            - guest_expired
                            - scheduled_deactivation
                        action:
                          type: string
                          enum:
                            - delete
                            - report
                            - suspend
                        due:
                          type: integer
                        sample_user_ids:
                          type: array
                          items:
                            type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/scheduled-deactivation:
    put:
      operationId: scheduleUserDeactivation
      tags:
        - Users
      summary: Schedule an account deactivation
      description: >-
        At the given time the lifecycle job suspends the account (reason scheduled_deactivation), ending its sessions.
        Audited as user.deactivation_scheduled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.suspend
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - at
              properties:
                at:
                  type: string
                  format: date-time
                reason:
                  type: string
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                  deactivate_at:
                    type: string
                    format: date-time
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: cancelUserDeactivation
      tags:
        - Users
      summary: Cancel a scheduled deactivation
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.suspend
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/user-bulk-operations:
    post:
      operationId: createUserBulkOperation
      tags:
        - Users
      summary: Apply one action to many accounts
      description: >-
        Runs as a checkpointed user.bulk job (USR-016): each account is validated and changed in its own transaction,
        protected accounts and the requester are skipped for suspend and lock, and the job result reports only account
        IDs with outcome (applied, valid, skipped, failed) and a stable code. Permissions: realm.users.suspend for
        suspend, reactivate and lock; realm.users.sessions.revoke for revoke_sessions; realm.users.required_actions for
        add_required_action; all re-checked when the job runs. Requires an MFA session. dry_run validates without
        changing anything; Idempotency-Key returns the same job for a retried submission.
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - action
                - user_ids
                - reason
              properties:
                action:
                  type: string
                  enum:
                    - suspend
                    - reactivate
                    - lock
                    - revoke_sessions
                    - add_required_action
                user_ids:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  uniqueItems: true
                  items:
                    type: string
                reason:
                  type: string
                  minLength: 5
                  maxLength: 500
                required_action:
                  type: string
                  description: The required action to add (add_required_action only).
                dry_run:
                  type: boolean
      responses:
        '202':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                  dry_run:
                    type: boolean
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/external-ids:
    get:
      operationId: listUserExternalIds
      tags:
        - Users
      summary: List an account's external IDs
      description: >-
        Connector-scoped IDs (USR-017), including mappings recorded by user imports. External IDs are unique only within
        their source system.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        source_system:
                          type: string
                        external_id:
                          type: string
                        job_id:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/external-ids/{source}:
    put:
      operationId: setUserExternalId
      tags:
        - Users
      summary: Set an account's ID in a source system
      description: >-
        Replaces the previous value in that system; a value mapped to another account in the same system conflicts
        (409). Audited as user.external_id.set.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/Path_source'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - external_id
              properties:
                external_id:
                  type: string
                  minLength: 1
                  maxLength: 256
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  source_system:
                    type: string
                  external_id:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: removeUserExternalId
      tags:
        - Users
      summary: Remove an account's ID in a source system
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/Path_source'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/external-ids/{source}/{id}:
    get:
      operationId: resolveExternalId
      tags:
        - Users
      summary: Resolve an external ID to an account
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_source'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  source_system:
                    type: string
                  external_id:
                    type: string
                  user_id:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/consents:
    get:
      operationId: listUserConsents
      tags:
        - Users
      summary: List a user's consents
      description: >-
        Consent records with client, scopes, resources, terms version, mode (user or preauthorized), grant and
        revocation times (APP-013).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/QueryHistory'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Consent'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/consents/{id}:
    delete:
      operationId: revokeUserConsent
      tags:
        - Users
      summary: Revoke a user's consent
      description: Ends the client's grants for the user; audited as consent.revoked.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/clients/{client}/consent-preauthorizations:
    get:
      operationId: listConsentPreauthorizations
      tags:
        - Clients
      summary: List consent pre-authorizations
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        client:
                          type: string
                        organization_id:
                          type: string
                        scopes:
                          type: array
                          items:
                            type: string
                        terms_version:
                          type: string
                        reason:
                          type: string
                        granted_by_id:
                          type: string
                        granted_at:
                          type: string
                          format: date-time
                        revoked_at:
                          type: string
                          format: date-time
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createConsentPreauthorization
      tags:
        - Clients
      summary: Pre-authorize a client on behalf of users
      description: >-
        Administrative consent (APP-013) for the client's current terms version, realm-wide or for one organization.
        Users signing in are not asked for the covered scopes; their consent is recorded with mode preauthorized.
        offline_access always needs the user's own consent.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - scopes
                - reason
              properties:
                organization_id:
                  type: string
                  description: Limit the pre-authorization to users signing in to this organization; omit for the whole realm.
                scopes:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: string
                reason:
                  type: string
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  client:
                    type: string
                  organization_id:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
                  terms_version:
                    type: string
                  reason:
                    type: string
                  granted_by_id:
                    type: string
                  granted_at:
                    type: string
                    format: date-time
                  revoked_at:
                    type: string
                    format: date-time
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/clients/{client}/consent-preauthorizations/{id}:
    delete:
      operationId: revokeConsentPreauthorization
      tags:
        - Clients
      summary: Revoke a consent pre-authorization
      description: Also revokes every consent recorded under it and the grants built on those consents.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/join-requests/{id}/reviewers:
    post:
      operationId: assignJoinReviewers
      tags:
        - Organizations
      summary: Assign reviewers to a join request
      description: >-
        Only the assigned reviewers (or a member administrator) may then decide (INV-013). Every reviewer must hold
        org.join_requests.review in the organization and none may be the requester; assignees are notified without the
        requester being named.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.members.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - reviewer_ids
              properties:
                reviewer_ids:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/join-requests/{id}/withdraw:
    post:
      operationId: withdrawJoinRequest
      tags:
        - Self-service
      summary: Withdraw my join request
      description: Ends a pending request and releases its pending_approval membership.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/join-requests:
    get:
      operationId: listMyJoinRequests
      tags:
        - Self-service
      summary: List my join requests
      description: Organization, state and dates only; reviewers and other requests are never shown.
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/JoinRequest'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/notification-settings/smtp:
    get:
      operationId: getOrganizationSMTP
      tags:
        - Organizations
      summary: Read the organization's own mail server
      description: Customer-owned mail server (TEN-022); the password is never returned (has_password says whether one is stored).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  host:
                    type: string
                  port:
                    type: integer
                    enum:
                      - 25
                      - 465
                      - 587
                      - 2525
                  username:
                    type: string
                  tls_mode:
                    type: string
                    enum:
                      - starttls
                      - implicit
                  has_password:
                    type: boolean
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: setOrganizationSMTP
      tags:
        - Organizations
      summary: Set the organization's own mail server
      description: >-
        The organization's mail is then sent through this server. TLS is required (starttls or implicit). The password
        is encrypted and bound to the realm and organization, so it can only be used for this organization's mail;
        connections go only to addresses the delivery egress policy allows. Requires an MFA session; audited as
        notification.smtp.updated without the secret.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - host
                - port
                - tls_mode
              properties:
                host:
                  type: string
                port:
                  type: integer
                  enum:
                    - 25
                    - 465
                    - 587
                    - 2525
                username:
                  type: string
                  maxLength: 256
                tls_mode:
                  type: string
                  enum:
                    - starttls
                    - implicit
                password:
                  type: string
                  format: password
                  x-secret: true
                  description: Omit to keep the stored password. Never returned.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  host:
                    type: string
                  port:
                    type: integer
                    enum:
                      - 25
                      - 465
                      - 587
                      - 2525
                  username:
                    type: string
                  tls_mode:
                    type: string
                    enum:
                      - starttls
                      - implicit
                  has_password:
                    type: boolean
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: clearOrganizationSMTP
      tags:
        - Organizations
      summary: Remove the organization's own mail server
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organization-templates:
    get:
      operationId: listOrganizationTemplates
      tags:
        - Organizations
      summary: List organization templates
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.organizations.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/QueryTemplateName'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        version:
                          type: integer
                        description:
                          type: string
                        document:
                          type: object
                          additionalProperties: false
                          properties:
                            policy:
                              type: object
                              description: Organization policy (same members as the organization policy object).
                            roles:
                              type: array
                              maxItems: 50
                              items:
                                type: object
                                additionalProperties: false
                                required:
                                  - name
                                  - permissions
                                properties:
                                  name:
                                    type: string
                                    maxLength: 100
                                  description:
                                    type: string
                                  permissions:
                                    type: array
                                    minItems: 1
                                    maxItems: 100
                                    items:
                                      type: string
                            groups:
                              type: array
                              maxItems: 50
                              items:
                                type: object
                                additionalProperties: false
                                required:
                                  - name
                                properties:
                                  name:
                                    type: string
                                    maxLength: 200
                                  description:
                                    type: string
                                  role_names:
                                    type: array
                                    maxItems: 20
                                    items:
                                      type: string
                            service_principals:
                              type: array
                              maxItems: 20
                              description: >-
                                Organization-owned service principals, named <organization slug>-<name>, with
                                organization roles. Credentials are never issued by a template. Applying needs
                                org.service_principals.write.
                              items:
                                type: object
                                additionalProperties: false
                                required:
                                  - name
                                properties:
                                  name:
                                    type: string
                                    pattern: ^[a-z0-9][a-z0-9-]{0,62}$
                                  description:
                                    type: string
                                    maxLength: 500
                                  role_names:
                                    type: array
                                    maxItems: 20
                                    items:
                                      type: string
                            webhooks:
                              type: array
                              maxItems: 20
                              description: >-
                                Webhook subscriptions scoped to the organization (https destinations checked against the
                                egress policy; no private networks). Applying needs org.integrations.write; each new
                                subscription signing secret is returned once in webhook_secrets.
                              items:
                                type: object
                                additionalProperties: false
                                required:
                                  - name
                                  - destination_url
                                  - event_types
                                properties:
                                  name:
                                    type: string
                                    maxLength: 200
                                  destination_url:
                                    type: string
                                    format: uri
                                    pattern: ^https://
                                  event_types:
                                    type: array
                                    minItems: 1
                                    items:
                                      type: string
                                  payload_form:
                                    type: string
                                    enum:
                                      - minimal
                                      - standard
                                    default: minimal
                        created_by_id:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: saveOrganizationTemplate
      tags:
        - Organizations
      summary: Save a new organization template version
      description: >-
        Versioned onboarding templates (TEN-017): policy, custom roles, groups with their roles, organization-owned
        service principals with their roles, and organization webhooks. Template roles cannot carry realm or support
        permissions. Each save creates the next version; versions are immutable.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.organizations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - name
                - document
              properties:
                name:
                  type: string
                  pattern: ^[a-z0-9][a-z0-9-]{0,62}$
                description:
                  type: string
                document:
                  type: object
                  additionalProperties: false
                  properties:
                    policy:
                      type: object
                      description: Organization policy (same members as the organization policy object).
                    roles:
                      type: array
                      maxItems: 50
                      items:
                        type: object
                        additionalProperties: false
                        required:
                          - name
                          - permissions
                        properties:
                          name:
                            type: string
                            maxLength: 100
                          description:
                            type: string
                          permissions:
                            type: array
                            minItems: 1
                            maxItems: 100
                            items:
                              type: string
                    groups:
                      type: array
                      maxItems: 50
                      items:
                        type: object
                        additionalProperties: false
                        required:
                          - name
                        properties:
                          name:
                            type: string
                            maxLength: 200
                          description:
                            type: string
                          role_names:
                            type: array
                            maxItems: 20
                            items:
                              type: string
                    service_principals:
                      type: array
                      maxItems: 20
                      description: >-
                        Organization-owned service principals, named <organization slug>-<name>, with organization
                        roles. Credentials are never issued by a template. Applying needs org.service_principals.write.
                      items:
                        type: object
                        additionalProperties: false
                        required:
                          - name
                        properties:
                          name:
                            type: string
                            pattern: ^[a-z0-9][a-z0-9-]{0,62}$
                          description:
                            type: string
                            maxLength: 500
                          role_names:
                            type: array
                            maxItems: 20
                            items:
                              type: string
                    webhooks:
                      type: array
                      maxItems: 20
                      description: >-
                        Webhook subscriptions scoped to the organization (https destinations checked against the egress
                        policy; no private networks). Applying needs org.integrations.write; each new subscription
                        signing secret is returned once in webhook_secrets.
                      items:
                        type: object
                        additionalProperties: false
                        required:
                          - name
                          - destination_url
                          - event_types
                        properties:
                          name:
                            type: string
                            maxLength: 200
                          destination_url:
                            type: string
                            format: uri
                            pattern: ^https://
                          event_types:
                            type: array
                            minItems: 1
                            items:
                              type: string
                          payload_form:
                            type: string
                            enum:
                              - minimal
                              - standard
                            default: minimal
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  version:
                    type: integer
                  description:
                    type: string
                  document:
                    type: object
                    additionalProperties: false
                    properties:
                      policy:
                        type: object
                        description: Organization policy (same members as the organization policy object).
                      roles:
                        type: array
                        maxItems: 50
                        items:
                          type: object
                          additionalProperties: false
                          required:
                            - name
                            - permissions
                          properties:
                            name:
                              type: string
                              maxLength: 100
                            description:
                              type: string
                            permissions:
                              type: array
                              minItems: 1
                              maxItems: 100
                              items:
                                type: string
                      groups:
                        type: array
                        maxItems: 50
                        items:
                          type: object
                          additionalProperties: false
                          required:
                            - name
                          properties:
                            name:
                              type: string
                              maxLength: 200
                            description:
                              type: string
                            role_names:
                              type: array
                              maxItems: 20
                              items:
                                type: string
                      service_principals:
                        type: array
                        maxItems: 20
                        description: >-
                          Organization-owned service principals, named <organization slug>-<name>, with organization
                          roles. Credentials are never issued by a template. Applying needs
                          org.service_principals.write.
                        items:
                          type: object
                          additionalProperties: false
                          required:
                            - name
                          properties:
                            name:
                              type: string
                              pattern: ^[a-z0-9][a-z0-9-]{0,62}$
                            description:
                              type: string
                              maxLength: 500
                            role_names:
                              type: array
                              maxItems: 20
                              items:
                                type: string
                      webhooks:
                        type: array
                        maxItems: 20
                        description: >-
                          Webhook subscriptions scoped to the organization (https destinations checked against the
                          egress policy; no private networks). Applying needs org.integrations.write; each new
                          subscription signing secret is returned once in webhook_secrets.
                        items:
                          type: object
                          additionalProperties: false
                          required:
                            - name
                            - destination_url
                            - event_types
                          properties:
                            name:
                              type: string
                              maxLength: 200
                            destination_url:
                              type: string
                              format: uri
                              pattern: ^https://
                            event_types:
                              type: array
                              minItems: 1
                              items:
                                type: string
                            payload_form:
                              type: string
                              enum:
                                - minimal
                                - standard
                              default: minimal
                  created_by_id:
                    type: string
                  created_at:
                    type: string
                    format: date-time
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/template-applications:
    post:
      operationId: applyOrganizationTemplate
      tags:
        - Organizations
      summary: Apply an organization template
      description: >-
        Plans (dry_run) or applies a template version in one transaction. Missing roles, groups, group grants, service
        principals, their grants and webhooks are created with the caller's authority (delegation ceilings apply;
        service principals need org.service_principals.write and webhooks org.integrations.write, otherwise the plan
        lists a conflict); a differing policy is replaced; existing roles with other permissions are conflicts, never
        rewritten, and a non-dry-run application with conflicts fails with 409. Grants that direct assignment (POST
        /role-assignments) would hold for an independent approver (a role that requires approval, or a privileged role
        for an agent service principal, MCH-017) are conflicts too ("... needs an independent approver: assign it
        through POST /role-assignments"); once such a grant is approved directly, the template reports it unchanged.
        Re-applying is idempotent. Audited as organization.template.applied.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.update
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - template
              properties:
                template:
                  type: string
                version:
                  type: integer
                  minimum: 1
                  description: Omit for the latest version.
                dry_run:
                  type: boolean
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    type: string
                  version:
                    type: integer
                  create:
                    type: array
                    items:
                      type: string
                  update:
                    type: array
                    items:
                      type: string
                  unchanged:
                    type: array
                    items:
                      type: string
                  conflicts:
                    type: array
                    items:
                      type: string
                  applied:
                    type: boolean
                  webhook_secrets:
                    type: object
                    additionalProperties:
                      type: string
                    description: >-
                      Signing secret of each webhook this application created, by name; shown once (Cache-Control
                      no-store, never replayed for an Idempotency-Key).
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/groups/{group}/dynamic-rule:
    get:
      operationId: getGroupDynamicRule
      tags:
        - Organizations
      summary: Read a group's dynamic membership rule
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_group'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  rule:
                    type: object
                    additionalProperties: false
                    required:
                      - all
                    properties:
                      all:
                        type: array
                        minItems: 1
                        maxItems: 5
                        items:
                          type: object
                          additionalProperties: false
                          required:
                            - attribute
                          properties:
                            attribute:
                              type: string
                              description: A profile attribute users cannot edit themselves.
                            equals:
                              type: string
                            in:
                              type: array
                              maxItems: 20
                              items:
                                type: string
                  recomputed_at:
                    type: string
                    format: date-time
                  member_count:
                    type: integer
                  error:
                    type: string
                    description: Set when the rule no longer validates; rule-derived members are then removed.
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: setGroupDynamicRule
      tags:
        - Organizations
      summary: Make a group dynamic
      description: >-
        Derives members from authoritative attributes (TEN-014): active members whose profile matches every condition.
        Attributes users can edit are refused, so nobody joins by editing their own profile. The caller must be able to
        assign every role the group grants. Manual members are removed, manual changes are then refused (409), and the
        worker recomputes every 10 minutes (groups.dynamic). A rule that stops validating fails closed.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_group'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - all
              properties:
                all:
                  type: array
                  minItems: 1
                  maxItems: 5
                  items:
                    type: object
                    additionalProperties: false
                    required:
                      - attribute
                    properties:
                      attribute:
                        type: string
                        description: A profile attribute users cannot edit themselves.
                      equals:
                        type: string
                      in:
                        type: array
                        maxItems: 20
                        items:
                          type: string
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  rule:
                    type: object
                    additionalProperties: false
                    required:
                      - all
                    properties:
                      all:
                        type: array
                        minItems: 1
                        maxItems: 5
                        items:
                          type: object
                          additionalProperties: false
                          required:
                            - attribute
                          properties:
                            attribute:
                              type: string
                              description: A profile attribute users cannot edit themselves.
                            equals:
                              type: string
                            in:
                              type: array
                              maxItems: 20
                              items:
                                type: string
                  recomputed_at:
                    type: string
                    format: date-time
                  member_count:
                    type: integer
                  error:
                    type: string
                    description: Set when the rule no longer validates; rule-derived members are then removed.
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: clearGroupDynamicRule
      tags:
        - Organizations
      summary: Make a group static again
      description: Keeps the current members as rule-derived until removed by hand.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.groups.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_group'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/aliases:
    get:
      operationId: listOrganizationAliases
      tags:
        - Organizations
      summary: List an organization's aliases
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: addOrganizationAlias
      tags:
        - Organizations
      summary: Add an organization alias
      description: >-
        Aliases (TEN-011) resolve wherever an organization slug is accepted and cannot be another organization's slug or
        alias (409). A renamed organization keeps its former slug as an alias automatically.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.update
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - alias
              properties:
                alias:
                  type: string
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/aliases/{alias}:
    delete:
      operationId: removeOrganizationAlias
      tags:
        - Organizations
      summary: Remove an organization alias
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.update
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_alias'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/audit-legal-holds:
    get:
      operationId: listAuditLegalHolds
      tags:
        - Audit
      summary: List audit legal holds
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.audit.legal_hold
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        organization_id:
                          type: string
                        subject_id:
                          type: string
                        reason:
                          type: string
                        created_by_id:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        released_by_id:
                          type: string
                        released_at:
                          type: string
                          format: date-time
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: placeAuditLegalHold
      tags:
        - Audit
      summary: Place an audit legal hold
      description: >-
        Events matching an active hold (realm, optionally one organization and/or one subject as subject or actor) are
        never removed by retention (AUD-009). Requires an MFA session; audited as audit.legal_hold.placed.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.audit.legal_hold
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - reason
              properties:
                organization_id:
                  type: string
                  description: Hold one organization's evidence; omit for the whole realm.
                subject_id:
                  type: string
                  description: Hold evidence about or by one subject.
                reason:
                  type: string
                  minLength: 5
                  maxLength: 500
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  organization_id:
                    type: string
                  subject_id:
                    type: string
                  reason:
                    type: string
                  created_by_id:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  released_by_id:
                    type: string
                  released_at:
                    type: string
                    format: date-time
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/audit-legal-holds/{id}/release:
    post:
      operationId: releaseAuditLegalHold
      tags:
        - Audit
      summary: Release an audit legal hold
      description: Retention applies to the held events again from the next run.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.audit.legal_hold
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/activity-events:
    post:
      operationId: reportApplicationActivity
      tags:
        - Audit
      summary: Report application activity
      description: >-
        Services (not users) report their own activity into the audit log (AUD-013). Reported events carry source
        application, the reporting service (client ID) and category application, use the app. type namespace so they can
        never pass for server-generated evidence, and are sealed into the same hash chain.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - realm.activity.report
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - type
              properties:
                type:
                  type: string
                  pattern: ^app\.[a-z0-9_.]{1,96}$
                occurred_at:
                  type: string
                  format: date-time
                  description: Within the last 24 hours (and at most 5 minutes ahead); defaults to now.
                organization_id:
                  type: string
                subject:
                  type: object
                  additionalProperties: false
                  properties:
                    type:
                      type: string
                      enum:
                        - user
                        - service_principal
                    id:
                      type: string
                outcome:
                  type: string
                  enum:
                    - success
                    - failure
                    - denied
                metadata:
                  type: object
                  description: At most 4 KiB; secret-like keys are redacted before storage.
      responses:
        '202':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  source:
                    type: string
                    enum:
                      - application
                  reporting_service:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/webhooks/{id}/backlog:
    get:
      operationId: getWebhookBacklog
      tags:
        - Webhooks
      summary: Read a subscription's delivery backlog
      description: >-
        Per-destination backlog (EXT-005): deliveries by state, the age of the oldest due delivery, the last successful
        delivery and the last failure category.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.webhooks.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  pending:
                    type: integer
                  retrying:
                    type: integer
                  dead_letter:
                    type: integer
                  delivered:
                    type: integer
                  oldest_due_seconds:
                    type: integer
                  last_delivered_at:
                    type: string
                    format: date-time
                  last_failure_category:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/hooks/{id}/diagnostics:
    get:
      operationId: getHookDiagnostics
      tags:
        - Hooks
      summary: Read a hook's recent invocations
      description: >-
        Extension diagnostics (EXT-017): the last 100 invocations with outcome, latency and a coarse error category,
        plus health and latency percentiles. Payloads, responses and secrets are never recorded; records are kept for 7
        days.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.hooks.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  health:
                    type: string
                    enum:
                      - healthy
                      - degraded
                      - unknown
                  recent_invocations:
                    type: integer
                  recent_failures:
                    type: integer
                  latency_p50_ms:
                    type: integer
                  latency_p95_ms:
                    type: integer
                  invocations:
                    type: array
                    items:
                      type: object
                      properties:
                        invoked_at:
                          type: string
                          format: date-time
                        outcome:
                          type: string
                          enum:
                            - ok
                            - failure
                        latency_ms:
                          type: integer
                        error_category:
                          type: string
                          enum:
                            - status
                            - egress_denied
                            - timeout
                            - malformed_response
                            - unreachable
                            - error
                        status_code:
                          type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/user-import-formats:
    get:
      operationId: listUserImportFormats
      tags:
        - Imports and exports
      summary: List supported user import formats
      description: >-
        The import formats this release accepts (MIG-002), each with the source products it covers, its schema, what it
        carries over and what it cannot. POST /user-imports declares one in format; compatibility is never inferred from
        source_system.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.import
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        format:
                          type: string
                        source_products:
                          type: array
                          items:
                            type: string
                        schema:
                          type: string
                        supports:
                          type: array
                          items:
                            type: string
                        unsupported:
                          type: array
                          items:
                            type: string
                      required:
                        - format
                        - source_products
                        - schema
                        - supports
                        - unsupported
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/user-imports/reconciliation:
    get:
      operationId: reconcileUserImport
      tags:
        - Imports and exports
      summary: Reconcile imported users with the source
      description: >-
        Counts what the realm holds now for the users imported from one source_system (MIG-012): accounts by state,
        memberships, privileged assignments, sign-in methods and verified emails. Expected counts from the source
        export, given as expected_* parameters, are compared and every difference is listed in mismatches. Returns no
        credentials or contact data. 404 when nothing was imported from the source.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.import
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: source_system
          in: query
          required: true
          schema:
            type: string
          description: The source_system of the imports.
        - name: expected_users
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Expected number of (non-deleted) accounts.
        - name: expected_memberships
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Expected number of active memberships.
        - name: expected_privileged_assignments
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Expected number of privileged role assignments.
        - name: expected_password_verifiers
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Expected number of accounts with a password.
        - name: expected_totp_factors
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Expected number of accounts with TOTP.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  source_system:
                    type: string
                  generated_at:
                    type: string
                    format: date-time
                  mappings:
                    type: object
                    description: >-
                      Import mappings of the source system, total and by current account state (deleted for accounts
                      deleted since import, missing when the account row no longer exists).
                    properties:
                      total:
                        type: integer
                      by_state:
                        type: object
                        additionalProperties:
                          type: integer
                  users:
                    type: integer
                    description: Mapped accounts that are not deleted.
                  memberships:
                    type: object
                    properties:
                      active:
                        type: integer
                      from_import:
                        type: integer
                      organizations:
                        type: integer
                  privileged_assignments:
                    type: object
                    description: >-
                      Role assignments of mapped accounts whose role is privileged (an owner role, a realm role, or a
                      role with a permission the catalog marks privileged, directly or through a composed role). At most
                      200 items.
                    properties:
                      total:
                        type: integer
                      truncated:
                        type: boolean
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            user_id:
                              type: string
                            source_id:
                              type: string
                            role:
                              type: string
                            scope_type:
                              type: string
                            scope_id:
                              type: string
                            assignment_source:
                              type: string
                  credentials:
                    type: object
                    description: >-
                      Accounts (not credentials) with each kind of sign-in method; without_sign_in_method counts
                      accounts with no password, passkey or federated link, which must recover or enroll.
                    properties:
                      password:
                        type: integer
                      password_not_yet_rehashed:
                        type: integer
                      totp:
                        type: integer
                      passkey:
                        type: integer
                      federated:
                        type: integer
                      without_sign_in_method:
                        type: integer
                  verified_emails:
                    type: integer
                  signed_in_since:
                    type: integer
                  subject_continuity:
                    type: object
                    properties:
                      resolvable_source_ids:
                        type: integer
                      deleted_since_import:
                        type: integer
                  mismatches:
                    type: array
                    items:
                      type: object
                      properties:
                        measure:
                          type: string
                          enum:
                            - users
                            - memberships
                            - privileged_assignments
                            - password_verifiers
                            - totp_factors
                        expected:
                          type: integer
                        actual:
                          type: integer
                  reconciled:
                    type: boolean
                    description: True when every expected_* count given matches.
                required:
                  - source_system
                  - mappings
                  - users
                  - memberships
                  - privileged_assignments
                  - credentials
                  - mismatches
                  - reconciled
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/audit-imports:
    post:
      operationId: importAuditHistory
      tags:
        - Audit
      summary: Import historical audit records
      description: >-
        Files historical events from a source system (MIG-016) apart from the evidence this server witnessed: they are
        never sealed into the local hash chain, are always reported with source import and verified false, and keep the
        source identifiers. Each record is checked on its own; the inserts and one local audit.history.imported event,
        which commits to the records through batch_digest, are stored together. Requires an MFA session. Imported
        records are kept for the retention period counted from the import (category imported of
        privacy.audit_retention_by_category, else privacy.audit_retention), subject to legal holds; deleting an account
        removes the metadata, source subject ID and actor display name of imported records about it.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.audit.import
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source_system:
                  type: string
                  pattern: ^[a-z0-9][a-z0-9._-]{0,62}$
                  description: >-
                    Source system name; subject_source_id values are mapped through the user import mappings of the same
                    name.
                events:
                  type: array
                  minItems: 1
                  maxItems: 500
                  items:
                    type: object
                    properties:
                      source_event_id:
                        type: string
                        minLength: 1
                        maxLength: 256
                        description: >-
                          The event ID in the source; a value already imported from the same source is a duplicate and
                          left unchanged.
                      occurred_at:
                        type: string
                        format: date-time
                        description: When the source says the event happened; any time in the past.
                      type:
                        type: string
                        pattern: ^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,127}$
                        description: The source event type, kept as given.
                      organization:
                        type: string
                        description: Organization ID or slug in this realm.
                      actor:
                        type: object
                        properties:
                          type:
                            type: string
                            maxLength: 64
                          id:
                            type: string
                            maxLength: 256
                          display:
                            type: string
                            maxLength: 256
                        required:
                          - type
                        additionalProperties: false
                      subject_source_id:
                        type: string
                        maxLength: 256
                        description: The subject user ID in the source system.
                      outcome:
                        type: string
                        enum:
                          - success
                          - failure
                          - denied
                          - unknown
                        default: unknown
                      metadata:
                        type: object
                        additionalProperties: {}
                        description: At most 4 KiB of JSON.
                    required:
                      - source_event_id
                      - occurred_at
                      - type
                    additionalProperties: false
              required:
                - source_system
                - events
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  batch_id:
                    type: string
                  counts:
                    type: object
                    additionalProperties:
                      type: integer
                  batch_digest:
                    type: string
                    description: >-
                      Hex SHA-256 over the content_hash of every record imported by this request, in order; also
                      recorded in the local audit.history.imported event.
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                        source_event_id:
                          type: string
                        status:
                          type: string
                          enum:
                            - imported
                            - duplicate
                            - error
                        id:
                          type: string
                        subject_id:
                          type: string
                        error:
                          type: string
                required:
                  - batch_id
                  - counts
                  - batch_digest
                  - results
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/imported-audit-events:
    get:
      operationId: listImportedAuditEvents
      tags:
        - Audit
      summary: List imported historical audit records
      description: >-
        Imported historical records (MIG-016), newest occurred_at first, at most 1000 per query before pagination. They
        are never returned by GET /audit-events.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.audit.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
        - name: source_system
          in: query
          required: false
          schema:
            type: string
          description: Filter by source system.
        - name: subject_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by mapped local account.
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by organization.
        - name: type
          in: query
          required: false
          schema:
            type: string
          description: Exact source event type.
        - name: batch_id
          in: query
          required: false
          schema:
            type: string
          description: Records of one import request.
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Earliest occurred_at (RFC 3339).
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Occurred before (RFC 3339).
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        source:
                          type: string
                          enum:
                            - import
                        verified:
                          type: boolean
                          enum:
                            - false
                        source_system:
                          type: string
                        source_event_id:
                          type: string
                        occurred_at:
                          type: string
                          format: date-time
                        type:
                          type: string
                        organization_id:
                          type: string
                        actor:
                          type: object
                          properties:
                            type:
                              type: string
                            id:
                              type: string
                            display:
                              type: string
                        subject_id:
                          type: string
                          description: The local account mapped from source_subject_id when the record was imported.
                        source_subject_id:
                          type: string
                        outcome:
                          type: string
                        metadata:
                          type: object
                          additionalProperties: {}
                        content_hash:
                          type: string
                          description: Hex SHA-256 of the record as submitted.
                        batch_id:
                          type: string
                        imported_at:
                          type: string
                          format: date-time
                        imported_by:
                          type: object
                          properties:
                            type:
                              type: string
                            id:
                              type: string
                        redacted_at:
                          type: string
                          format: date-time
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/deletion-status:
    get:
      operationId: getUserDeletionStatus
      tags:
        - Users
      summary: Report how an account deletion has propagated
      description: >-
        PRV-005: for a deleted account, the state of every place its data lived, derived from what is stored now:
        primary storage, sessions and grants, export results (until privacy.export_retention after the deletion),
        notification payloads and recipients, connectors (the user.deleted event and its webhook deliveries; pending
        while any is undelivered), imported audit history (pending while source-supplied details remain unredacted,
        which a legal hold keeps), caches (until the decision cache TTL, at least a minute), audit evidence (retained by
        ID until the longest applicable audit retention after the deletion: privacy.audit_retention, any
        privacy.audit_retention_by_category override and the realm's audit.retention_days; organization retention may
        keep their organization's events longer; with an active legal hold covering the account or the whole realm there
        is no until, as the hold keeps them until it is released; organization legal holds are mentioned in details) and
        backups (retained until privacy.backup_retention after the deletion, then done; unknown when it is not set;
        never reported erased early, and restore reconciliation re-applies the deletion). 404 for an unknown account;
        409 (with the extension state) when the account is not deleted.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                  deleted_at:
                    type: string
                    format: date-time
                  stages:
                    type: array
                    items:
                      type: object
                      properties:
                        stage:
                          type: string
                          enum:
                            - primary_storage
                            - sessions_and_grants
                            - exports
                            - notifications
                            - connectors
                            - imported_audit_history
                            - caches
                            - audit_evidence
                            - backups
                        state:
                          type: string
                          enum:
                            - done
                            - pending
                            - retained
                            - unknown
                        count:
                          type: integer
                        until:
                          type: string
                          format: date-time
                          description: When the stage is expected to finish (purge, retention or backup expiry).
                        details:
                          type: string
                      required:
                        - stage
                        - state
                        - details
                required:
                  - user_id
                  - deleted_at
                  - stages
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/custom-domains:
    get:
      operationId: listCustomDomains
      tags:
        - Realm
      summary: List custom domains
      description: >-
        Custom hostnames (DEP-014) on which the realm endpoints may be served besides the public origin. Under
        server.host_policy strict, only the public origin host and verified custom domains are served, each custom
        domain only for its own realm paths, and any other Host gets 421. A custom domain never changes the issuer or
        any subject: discovery and tokens keep the canonical issuer; cookies are per host; passkeys work there only when
        passkeys_usable is true.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        host:
                          type: string
                        state:
                          type: string
                          enum:
                            - pending
                            - verified
                        challenge_expires_at:
                          type: string
                          format: date-time
                        verified_at:
                          type: string
                          format: date-time
                        created_at:
                          type: string
                          format: date-time
                        passkeys_usable:
                          type: boolean
                          description: >-
                            True when the realm WebAuthn RP ID is this host or a parent domain, so the realm passkeys
                            work here.
                      required:
                        - id
                        - host
                        - state
                        - created_at
                        - passkeys_usable
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: addCustomDomain
      tags:
        - Realm
      summary: Add a custom domain
      description: >-
        Registers a host and returns a DNS TXT proof to publish at _proudauth-challenge.<host> within 7 days, then call
        verify. Requires an MFA session. Audited as realm.custom_domain.added.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                host:
                  type: string
                  description: A DNS name other than the public origin host.
              required:
                - host
              additionalProperties: false
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:
                    type: object
                    properties:
                      id:
                        type: string
                      host:
                        type: string
                      state:
                        type: string
                        enum:
                          - pending
                          - verified
                      challenge_expires_at:
                        type: string
                        format: date-time
                      verified_at:
                        type: string
                        format: date-time
                      created_at:
                        type: string
                        format: date-time
                      passkeys_usable:
                        type: boolean
                        description: >-
                          True when the realm WebAuthn RP ID is this host or a parent domain, so the realm passkeys work
                          here.
                    required:
                      - id
                      - host
                      - state
                      - created_at
                      - passkeys_usable
                  dns_record_name:
                    type: string
                  dns_record_type:
                    type: string
                    enum:
                      - TXT
                  dns_record_value:
                    type: string
                required:
                  - domain
                  - dns_record_name
                  - dns_record_type
                  - dns_record_value
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/custom-domains/{id}/verify:
    post:
      operationId: verifyCustomDomain
      tags:
        - Realm
      summary: Verify a custom domain
      description: >-
        Checks the DNS TXT proof (_proudauth-challenge.<host>, looked up for at most 5 seconds); a verified host starts
        serving the realm under a strict host policy. A domain that is already verified is returned unchanged (200). 422
        when the record is missing or wrong. 409 when the challenge expired (remove and add the domain again), the
        domain was removed, another realm verified the same host first (field host), or the domain changed while it was
        being verified. Requires an MFA session. Audited as realm.custom_domain.verified.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  host:
                    type: string
                  state:
                    type: string
                    enum:
                      - pending
                      - verified
                  challenge_expires_at:
                    type: string
                    format: date-time
                  verified_at:
                    type: string
                    format: date-time
                  created_at:
                    type: string
                    format: date-time
                  passkeys_usable:
                    type: boolean
                    description: >-
                      True when the realm WebAuthn RP ID is this host or a parent domain, so the realm passkeys work
                      here.
                required:
                  - id
                  - host
                  - state
                  - created_at
                  - passkeys_usable
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/custom-domains/{id}:
    delete:
      operationId: removeCustomDomain
      tags:
        - Realm
      summary: Remove a custom domain
      description: Stops serving the realm on the host at once. Requires an MFA session. Audited as realm.custom_domain.removed.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/scim/v2/ServiceProviderConfig:
    get:
      operationId: scimServiceProviderConfig
      tags:
        - Provisioning
      summary: SCIM service provider configuration
      description: 'Advertises exactly what is implemented: PATCH, filtering and ETags; no bulk, sort or password change (PROV-009).'
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimResource'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
  /api/v1/realms/{realm}/scim/v2/ResourceTypes:
    get:
      operationId: scimResourceTypes
      tags:
        - Provisioning
      summary: SCIM resource types
      description: Resource types the connector may use.
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimListResponse'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
  /api/v1/realms/{realm}/scim/v2/Schemas:
    get:
      operationId: scimSchemas
      tags:
        - Provisioning
      summary: SCIM schemas
      description: Attributes stored for Users and Groups; other attributes are accepted and ignored.
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimListResponse'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
  /api/v1/realms/{realm}/scim/v2/Users:
    get:
      operationId: scimListUsers
      tags:
        - Provisioning
      summary: List SCIM users
      description: >-
        Lists users provisioned by this connector in its organization. Supports filter (eq, ne, co, sw, ew, gt, ge, lt,
        le, pr, and, or, not, value paths), startIndex, count (at most 200), attributes and excludedAttributes.
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/ScimFilter'
        - $ref: '#/components/parameters/ScimStartIndex'
        - $ref: '#/components/parameters/ScimCount'
        - $ref: '#/components/parameters/ScimAttributes'
        - $ref: '#/components/parameters/ScimExcludedAttributes'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimListResponse'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
    post:
      operationId: scimCreateUser
      tags:
        - Provisioning
      summary: Create a SCIM user
      description: >-
        Provisions an account in the connector organization. An existing account is adopted only when its verified email
        is in a domain the organization has verified, and never when it is protected, privileged or mapped to another
        external ID (PROV-002, PROV-004).
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: SCIM JSON (application/scim+json or application/json); duplicate members are rejected.
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimUser'
          application/json:
            schema:
              $ref: '#/components/schemas/ScimUser'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              description: Weak entity tag of the resource version.
              schema:
                type: string
            Location:
              description: URL of the created resource.
              schema:
                type: string
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimResource'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
  /api/v1/realms/{realm}/scim/v2/Users/{id}:
    get:
      operationId: scimGetUser
      tags:
        - Provisioning
      summary: Get a SCIM user
      description: Returns a user provisioned by this connector.
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/ScimAttributes'
        - $ref: '#/components/parameters/ScimExcludedAttributes'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              description: Weak entity tag of the resource version.
              schema:
                type: string
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimResource'
        '304':
          description: Not Modified (If-None-Match matched the current ETag).
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
    put:
      operationId: scimReplaceUser
      tags:
        - Provisioning
      summary: Replace a SCIM user
      description: >-
        Replaces the user. Identity attributes change only on accounts this connector owns; active maps to the
        organization membership state, never the account state (PROV-005).
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/ScimIfMatch'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: SCIM JSON (application/scim+json or application/json); duplicate members are rejected.
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimUser'
          application/json:
            schema:
              $ref: '#/components/schemas/ScimUser'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              description: Weak entity tag of the resource version.
              schema:
                type: string
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimResource'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
    patch:
      operationId: scimPatchUser
      tags:
        - Provisioning
      summary: Patch a SCIM user
      description: Applies RFC 7644 PATCH operations (add, replace, remove; op names are case-insensitive).
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/ScimIfMatch'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: SCIM JSON (application/scim+json or application/json); duplicate members are rejected.
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimPatchOp'
          application/json:
            schema:
              $ref: '#/components/schemas/ScimPatchOp'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              description: Weak entity tag of the resource version.
              schema:
                type: string
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimResource'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
    delete:
      operationId: scimDeleteUser
      tags:
        - Provisioning
      summary: Delete a SCIM user
      description: >-
        Removes the user from the connector organization only; the account and other memberships are untouched
        (PROV-005).
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/ScimIfMatch'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
  /api/v1/realms/{realm}/scim/v2/Groups:
    get:
      operationId: scimListGroups
      tags:
        - Provisioning
      summary: List SCIM groups
      description: >-
        Lists groups provisioned by this connector in its organization. Supports filter (eq, ne, co, sw, ew, gt, ge, lt,
        le, pr, and, or, not, value paths), startIndex, count (at most 200), attributes and excludedAttributes.
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/ScimFilter'
        - $ref: '#/components/parameters/ScimStartIndex'
        - $ref: '#/components/parameters/ScimCount'
        - $ref: '#/components/parameters/ScimAttributes'
        - $ref: '#/components/parameters/ScimExcludedAttributes'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimListResponse'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
    post:
      operationId: scimCreateGroup
      tags:
        - Provisioning
      summary: Create a SCIM group
      description: >-
        Creates a group in the connector organization. Roles come only from the connector approved group mappings within
        its role ceiling (PROV-006). Members must be users this connector provisioned.
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: SCIM JSON (application/scim+json or application/json); duplicate members are rejected.
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimGroup'
          application/json:
            schema:
              $ref: '#/components/schemas/ScimGroup'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              description: Weak entity tag of the resource version.
              schema:
                type: string
            Location:
              description: URL of the created resource.
              schema:
                type: string
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimResource'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
  /api/v1/realms/{realm}/scim/v2/Groups/{id}:
    get:
      operationId: scimGetGroup
      tags:
        - Provisioning
      summary: Get a SCIM group
      description: Returns a group provisioned by this connector.
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/ScimAttributes'
        - $ref: '#/components/parameters/ScimExcludedAttributes'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              description: Weak entity tag of the resource version.
              schema:
                type: string
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimResource'
        '304':
          description: Not Modified (If-None-Match matched the current ETag).
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
    put:
      operationId: scimReplaceGroup
      tags:
        - Provisioning
      summary: Replace a SCIM group
      description: Replaces the group name and members.
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/ScimIfMatch'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: SCIM JSON (application/scim+json or application/json); duplicate members are rejected.
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimGroup'
          application/json:
            schema:
              $ref: '#/components/schemas/ScimGroup'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              description: Weak entity tag of the resource version.
              schema:
                type: string
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimResource'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
    patch:
      operationId: scimPatchGroup
      tags:
        - Provisioning
      summary: Patch a SCIM group
      description: Applies RFC 7644 PATCH operations (add, replace, remove; op names are case-insensitive).
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/ScimIfMatch'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: SCIM JSON (application/scim+json or application/json); duplicate members are rejected.
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimPatchOp'
          application/json:
            schema:
              $ref: '#/components/schemas/ScimPatchOp'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              description: Weak entity tag of the resource version.
              schema:
                type: string
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimResource'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
    delete:
      operationId: scimDeleteGroup
      tags:
        - Provisioning
      summary: Delete a SCIM group
      description: Deletes the group and its connector-sourced role assignments.
      security:
        - scimConnectorToken: []
      x-trust-class: provisioning
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/ScimIfMatch'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '400':
          $ref: '#/components/responses/ScimError'
        '401':
          $ref: '#/components/responses/ScimError'
        '403':
          $ref: '#/components/responses/ScimError'
        '404':
          $ref: '#/components/responses/ScimError'
        '409':
          $ref: '#/components/responses/ScimError'
        '412':
          $ref: '#/components/responses/ScimError'
        '429':
          $ref: '#/components/responses/ScimError'
        '500':
          $ref: '#/components/responses/ScimError'
  /api/v1/realms/{realm}/organizations/{org}/provisioning-connectors:
    get:
      operationId: listProvisioningConnectors
      tags:
        - Provisioning
      summary: List provisioning connectors
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProvisioningConnector'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createProvisioningConnector
      tags:
        - Provisioning
      summary: Create a provisioning connector
      description: >-
        Creates an inbound SCIM connector bound to the organization. The role ceiling must be within the creator own
        ceiling (PROV-003). The token is shown once. Requires an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisioningConnectorInput'
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  connector:
                    $ref: '#/components/schemas/ProvisioningConnector'
                  token:
                    type: string
                    description: Connector bearer token (pa_scim_...), shown once.
                  scim_base_url:
                    type: string
                required:
                  - connector
                  - token
                  - scim_base_url
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/provisioning-connectors/{id}:
    get:
      operationId: getProvisioningConnector
      tags:
        - Provisioning
      summary: Get a provisioning connector
      description: 'Includes operational evidence: last_sync_at, last_error and per-operation stats (PROV-018).'
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisioningConnector'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateProvisioningConnector
      tags:
        - Provisioning
      summary: Update a provisioning connector
      description: >-
        Replaces the connector settings; state disabled stops the token working at once. Requires If-Match and an MFA
        session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchRequired'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ProvisioningConnectorInput'
                - type: object
                  properties:
                    state:
                      type: string
                      enum:
                        - active
                        - disabled
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisioningConnector'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/provisioning-connectors/{id}/token:
    post:
      operationId: rotateProvisioningConnectorToken
      tags:
        - Provisioning
      summary: Rotate a connector token
      description: Issues a new token; the old one stops working at once. Requires an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                required:
                  - token
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/hooks/{id}/ownership-transfer:
    post:
      operationId: transferHookOwnership
      tags:
        - Hooks
      summary: Change the accountable owner of a pre-action hook
      description: >-
        DOM-009: sets owner_user_id (an active or recovery_restricted account of the realm) of a pre-action hook, also
        when it has none or its owner left; a plugin-managed part keeps its plugin (plugin_id). Audited as
        hook.ownership_transferred (metadata previous_owner_user_id, owner_user_id); the version moves. Honors If-Match.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.hooks.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                owner_user_id:
                  type: string
              required:
                - owner_user_id
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                type: object
                properties:
                  kind:
                    type: string
                    enum:
                      - hook
                  id:
                    type: string
                  owner_user_id:
                    type: string
                  previous_owner_user_id:
                    type: string
                    description: Empty when it had no owner.
                  version:
                    type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/webhooks/{id}/ownership-transfer:
    post:
      operationId: transferWebhookOwnership
      tags:
        - Webhooks
      summary: Change the accountable owner of a webhook subscription
      description: >-
        DOM-009: sets owner_user_id (an active or recovery_restricted account of the realm) of a webhook subscription,
        also when it has none or its owner left; a plugin-managed part keeps its plugin (plugin_id). Audited as
        webhook.ownership_transferred (metadata previous_owner_user_id, owner_user_id); the version moves. Honors
        If-Match.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.webhooks.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                owner_user_id:
                  type: string
              required:
                - owner_user_id
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                type: object
                properties:
                  kind:
                    type: string
                    enum:
                      - webhook
                  id:
                    type: string
                  owner_user_id:
                    type: string
                  previous_owner_user_id:
                    type: string
                    description: Empty when it had no owner.
                  version:
                    type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/policies/{policy}/ownership-transfer:
    post:
      operationId: transferPolicyOwnership
      tags:
        - Authorization
      summary: Change the accountable owner of an authorization policy
      description: >-
        DOM-009: sets owner_user_id (an active or recovery_restricted account of the realm) of an authorization policy,
        also when it has none or its owner left; a plugin-managed part keeps its plugin (plugin_id). Audited as
        authorization_policy.ownership_transferred (metadata previous_owner_user_id, owner_user_id); the version moves.
        Honors If-Match.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.policies.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_policy'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                owner_user_id:
                  type: string
              required:
                - owner_user_id
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                type: object
                properties:
                  kind:
                    type: string
                    enum:
                      - authorization_policy
                  id:
                    type: string
                  owner_user_id:
                    type: string
                  previous_owner_user_id:
                    type: string
                    description: Empty when it had no owner.
                  version:
                    type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/ownership-transfer:
    post:
      operationId: transferUserOwnership
      tags:
        - Users
      summary: Transfer everything a user owns
      description: >-
        Offboarding (USR-020): moves the projects, clients, service principals, resources, connections, pre-action
        hooks, webhook subscriptions and authorization policies the user owns to another active account (plugin-managed
        hooks and subscriptions keep their plugin); each move is audited as <kind>.ownership_transferred. Needs the
        write permission of every kind.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.projects.write
        - realm.clients.write
        - realm.service_principals.write
        - realm.resources.write
        - realm.identity_providers.write
        - realm.hooks.write
        - realm.webhooks.write
        - realm.policies.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to_user_id:
                  type: string
              required:
                - to_user_id
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  transferred:
                    type: object
                    additionalProperties:
                      type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/audit-events/{id}/corrections:
    post:
      operationId: correctAuditEvent
      tags:
        - Audit
      summary: Record a correction to an audit event
      description: >-
        Evidence is never edited (AUD-007): the correction is a new audit.correction event targeting the original
        (target_id), with the reason and the corrected values; both stay queryable.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.audit.correct
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  minLength: 5
                  maxLength: 1000
                correction:
                  type: object
                  additionalProperties: true
                  description: Corrected values, at most 8 KiB.
              required:
                - reason
              additionalProperties: false
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  event_id:
                    type: string
                  corrects_event_id:
                    type: string
                required:
                  - event_id
                  - corrects_event_id
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/invitations/{id}:
    get:
      operationId: getInvitation
      tags:
        - Invitations
      summary: Get an invitation
      description: One invitation of the organization with its state and an ETag (INV-001); the secret is never returned.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.invites.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/data-exports:
    post:
      operationId: createRealmDataExport
      tags:
        - Imports and exports
      summary: Export the realm data
      description: >-
        Portable exit (OSS-008, MIG-014): a job (realm.export) writes the realm as NDJSON records {kind, data} with
        stable IDs - header (format proudauth.realm-export.v1 and the excluded list), configuration, user, organization,
        membership, group, role_assignment, authorization_policy, project, service_principal, identity_provider,
        webhook, hook. Credential secrets, keys, live tokens and audit evidence are excluded. Download through POST
        /jobs/{id}/downloads; the permission is re-checked when the job runs and at download.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.data.export
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '202':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                required:
                  - job_id
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/ownership-report:
    get:
      operationId: getOwnershipReport
      tags:
        - Realm
      summary: Report objects without an accountable owner
      description: >-
        DOM-009, APP-014, MCH-007: live clients (with or without secrets), projects, service principals, resources,
        identity providers, webhooks, hooks and authorization policies that have no owner (no owner user, owning
        organization or client contacts) or whose owner is no longer active; flags ownerless and owner_departed.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        kind:
                          type: string
                        id:
                          type: string
                        name:
                          type: string
                        owner_user_id:
                          type: string
                        owner_organization_id:
                          type: string
                        flags:
                          type: array
                          items:
                            type: string
                            enum:
                              - ownerless
                              - owner_departed
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/clients/{client}/workload-trusts:
    get:
      operationId: listWorkloadTrusts
      tags:
        - Clients
      summary: List workload trusts
      description: >-
        Workload federation trusts of a client (MCH-011..MCH-013): external workload identity issuers whose assertions
        the client may exchange for its service principal's tokens with the jwt-bearer grant.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkloadTrust'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createWorkloadTrust
      tags:
        - Clients
      summary: Create a workload trust
      description: >-
        A credential change (audited as client.workload_trust.created). The client must be a machine client with a
        service principal and the urn:ietf:params:oauth:grant-type:jwt-bearer grant (409 otherwise). Profiles:
        github_actions (fixed issuer and key set, subject naming the repository, jti required), kubernetes (one service
        account: system:serviceaccount:<namespace>:<name>, no wildcards), spiffe (a SPIFFE ID or path prefix ending in
        /*; iss may be absent from JWT-SVIDs), generic (exact subject or one trailing *). Exactly one of jwks_uri and
        jwks; key sets from jwks_uri are fetched under the federation egress rules.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.credentials
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkloadTrustInput'
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadTrust'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/clients/{client}/workload-trusts/{id}:
    get:
      operationId: getWorkloadTrust
      tags:
        - Clients
      summary: Get a workload trust
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadTrust'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: replaceWorkloadTrust
      tags:
        - Clients
      summary: Replace a workload trust
      description: Requires If-Match (428 without it, 412 when stale). state=disabled stops the trust at once.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.credentials
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchRequired'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkloadTrustInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadTrust'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteWorkloadTrust
      tags:
        - Clients
      summary: Delete a workload trust
      description: Tokens already issued expire on their own (they never outlive the assertion they came from).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.credentials
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/oauth/register:
    post:
      operationId: registerClient
      tags:
        - OAuth
      summary: Dynamic client registration (RFC 7591)
      description: >-
        APP-016, ADV-003: only when the realm enables client_registration (404 otherwise). With an initial access token
        (Bearer) the client receives the non-privileged scopes the token allows; without one, only when the realm allows
        open registration, and the client is held for approval. Registered clients are third-party clients that ask for
        consent. 20 registrations per hour per network and 500 per realm (fails closed).
      security:
        - initialAccessToken: []
        - {}
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                Client metadata (RFC 7591). Unknown members are ignored. Accepted: redirect_uris (1 to 20, exact-match
                rules), post_logout_redirect_uris, token_endpoint_auth_method (client_secret_basic default,
                client_secret_post, private_key_jwt with inline jwks, none for public or native clients), grant_types
                (authorization_code, refresh_token), response_types ([code]), client_name, scope, contacts, jwks,
                software_id, software_version, client_uri, logo_uri, policy_uri, tos_uri (https, never fetched),
                frontchannel_logout_uri, response encryption and signing options. Refused: jwks_uri (no metadata
                fetching), software_statement, other grant and response types.
              properties:
                redirect_uris:
                  type: array
                  items:
                    type: string
                post_logout_redirect_uris:
                  type: array
                  items:
                    type: string
                token_endpoint_auth_method:
                  type: string
                  enum:
                    - client_secret_basic
                    - client_secret_post
                    - private_key_jwt
                    - none
                grant_types:
                  type: array
                  items:
                    type: string
                    enum:
                      - authorization_code
                      - refresh_token
                response_types:
                  type: array
                  items:
                    type: string
                    enum:
                      - code
                client_name:
                  type: string
                scope:
                  type: string
                contacts:
                  type: array
                  items:
                    type: string
                jwks:
                  type: object
                software_id:
                  type: string
                software_version:
                  type: string
                client_uri:
                  type: string
                logo_uri:
                  type: string
                policy_uri:
                  type: string
                tos_uri:
                  type: string
                rotate_secret:
                  type: boolean
                  description: >-
                    Management updates only (extension): issue a new client secret; the previous one stays valid for an
                    hour.
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Client information (RFC 7591 §3.2.1): the registered metadata plus client_id, client_id_issued_at,
                  client_secret and client_secret_expires_at (0: does not expire) when one was issued (only at
                  registration or on rotation), registration_access_token (at registration and after every update),
                  registration_client_uri, scope (what was granted), proudauth_approval_state (approved or pending) and
                  proudauth_client_state (a pending registration is suspended until approved).
                properties:
                  client_id:
                    type: string
                  client_secret:
                    type: string
                    x-secret: true
                  client_secret_expires_at:
                    type: integer
                  client_id_issued_at:
                    type: integer
                  registration_access_token:
                    type: string
                    x-secret: true
                  registration_client_uri:
                    type: string
                  scope:
                    type: string
                  proudauth_approval_state:
                    type: string
                    enum:
                      - approved
                      - pending
                  proudauth_client_state:
                    type: string
                additionalProperties: true
        '400':
          description: 'RFC 7591 error: invalid_redirect_uri, invalid_client_metadata or unapproved_software_statement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '401':
          description: Missing, invalid, expired, revoked or exhausted token (error invalid_token, WWW-Authenticate Bearer).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '404':
          description: Dynamic registration is not enabled in this realm.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/oauth/register/{client_id}:
    get:
      operationId: readClientRegistration
      tags:
        - OAuth
      summary: Read a registered client (RFC 7592)
      description: Authenticated by the client's registration access token.
      security:
        - registrationAccessToken: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - name: client_id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Client information (RFC 7591 §3.2.1): the registered metadata plus client_id, client_id_issued_at,
                  client_secret and client_secret_expires_at (0: does not expire) when one was issued (only at
                  registration or on rotation), registration_access_token (at registration and after every update),
                  registration_client_uri, scope (what was granted), proudauth_approval_state (approved or pending) and
                  proudauth_client_state (a pending registration is suspended until approved).
                properties:
                  client_id:
                    type: string
                  client_secret:
                    type: string
                    x-secret: true
                  client_secret_expires_at:
                    type: integer
                  client_id_issued_at:
                    type: integer
                  registration_access_token:
                    type: string
                    x-secret: true
                  registration_client_uri:
                    type: string
                  scope:
                    type: string
                  proudauth_approval_state:
                    type: string
                    enum:
                      - approved
                      - pending
                  proudauth_client_state:
                    type: string
                additionalProperties: true
        '400':
          description: 'RFC 7591 error: invalid_redirect_uri, invalid_client_metadata or unapproved_software_statement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '401':
          description: Missing, invalid, expired, revoked or exhausted token (error invalid_token, WWW-Authenticate Bearer).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '404':
          description: Dynamic registration is not enabled in this realm.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      operationId: updateClientRegistration
      tags:
        - OAuth
      summary: Update a registered client (RFC 7592)
      description: >-
        Replaces the registrant's metadata (client_id must match): client_name, redirect and post-logout redirect URIs,
        grant types, the authentication method within the client type, contacts, software_id/version and the protocol
        options. The client type and granted scopes cannot change, and settings an administrator controls through the
        client API (description, security profile and consent settings, offline access, remember-me, default resource,
        environment, project, owner, subject_type and sector_identifier, login UI and back-channel logout URIs, allowed
        origins, claim mappings, token_policy) are kept, not reset; metadata that conflicts with them is refused (for
        example redirect URIs outside a pairwise sector). A new registration_access_token is returned and the old one
        stops working; rotate_secret=true issues a new secret. The update is one transaction: when any part fails
        (invalid metadata, or a rotation beyond limits.client_secrets_max, which counts only secrets not yet expired:
        409), nothing changes and the presented registration access token stays valid.
      security:
        - registrationAccessToken: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - name: client_id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                Client metadata (RFC 7591). Unknown members are ignored. Accepted: redirect_uris (1 to 20, exact-match
                rules), post_logout_redirect_uris, token_endpoint_auth_method (client_secret_basic default,
                client_secret_post, private_key_jwt with inline jwks, none for public or native clients), grant_types
                (authorization_code, refresh_token), response_types ([code]), client_name, scope, contacts, jwks,
                software_id, software_version, client_uri, logo_uri, policy_uri, tos_uri (https, never fetched),
                frontchannel_logout_uri, response encryption and signing options. Refused: jwks_uri (no metadata
                fetching), software_statement, other grant and response types.
              properties:
                redirect_uris:
                  type: array
                  items:
                    type: string
                post_logout_redirect_uris:
                  type: array
                  items:
                    type: string
                token_endpoint_auth_method:
                  type: string
                  enum:
                    - client_secret_basic
                    - client_secret_post
                    - private_key_jwt
                    - none
                grant_types:
                  type: array
                  items:
                    type: string
                    enum:
                      - authorization_code
                      - refresh_token
                response_types:
                  type: array
                  items:
                    type: string
                    enum:
                      - code
                client_name:
                  type: string
                scope:
                  type: string
                contacts:
                  type: array
                  items:
                    type: string
                jwks:
                  type: object
                software_id:
                  type: string
                software_version:
                  type: string
                client_uri:
                  type: string
                logo_uri:
                  type: string
                policy_uri:
                  type: string
                tos_uri:
                  type: string
                rotate_secret:
                  type: boolean
                  description: >-
                    Management updates only (extension): issue a new client secret; the previous one stays valid for an
                    hour.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Client information (RFC 7591 §3.2.1): the registered metadata plus client_id, client_id_issued_at,
                  client_secret and client_secret_expires_at (0: does not expire) when one was issued (only at
                  registration or on rotation), registration_access_token (at registration and after every update),
                  registration_client_uri, scope (what was granted), proudauth_approval_state (approved or pending) and
                  proudauth_client_state (a pending registration is suspended until approved).
                properties:
                  client_id:
                    type: string
                  client_secret:
                    type: string
                    x-secret: true
                  client_secret_expires_at:
                    type: integer
                  client_id_issued_at:
                    type: integer
                  registration_access_token:
                    type: string
                    x-secret: true
                  registration_client_uri:
                    type: string
                  scope:
                    type: string
                  proudauth_approval_state:
                    type: string
                    enum:
                      - approved
                      - pending
                  proudauth_client_state:
                    type: string
                additionalProperties: true
        '400':
          description: 'RFC 7591 error: invalid_redirect_uri, invalid_client_metadata or unapproved_software_statement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '401':
          description: Missing, invalid, expired, revoked or exhausted token (error invalid_token, WWW-Authenticate Bearer).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '404':
          description: Dynamic registration is not enabled in this realm.
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteClientRegistration
      tags:
        - OAuth
      summary: Delete a registered client (RFC 7592)
      description: 'Decommissions the client: its grants and tokens end and its registration access token stops working.'
      security:
        - registrationAccessToken: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - name: client_id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '400':
          description: 'RFC 7591 error: invalid_redirect_uri, invalid_client_metadata or unapproved_software_statement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '401':
          description: Missing, invalid, expired, revoked or exhausted token (error invalid_token, WWW-Authenticate Bearer).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '404':
          description: Dynamic registration is not enabled in this realm.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/client-registration-tokens:
    get:
      operationId: listInitialAccessTokens
      tags:
        - Clients
      summary: List initial access tokens
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RegistrationToken'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createInitialAccessToken
      tags:
        - Clients
      summary: Issue an initial access token
      description: >-
        ADV-003 initial registration authority: allowed_scopes name business resources and non-privileged scopes
        registered clients may receive (privileged scopes are refused, and re-checked at use); max_uses defaults to 1,
        expiry to 7 days. The plaintext is returned once.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.credentials
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                description:
                  type: string
                  maxLength: 200
                allowed_scopes:
                  type: array
                  maxItems: 20
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      resource_id:
                        type: string
                      scopes:
                        type: array
                        items:
                          type: string
                    required:
                      - resource_id
                      - scopes
                project_id:
                  type: string
                max_uses:
                  type: integer
                  minimum: 1
                  maximum: 1000
                expires_in_seconds:
                  type: integer
                  minimum: 60
                  maximum: 7776000
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  initial_access_token:
                    type: string
                    x-secret: true
                  token:
                    $ref: '#/components/schemas/RegistrationToken'
                  notice:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/client-registration-tokens/{id}:
    delete:
      operationId: revokeInitialAccessToken
      tags:
        - Clients
      summary: Revoke an initial access token
      description: Clients already registered with it are unaffected.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.credentials
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/client-registrations:
    get:
      operationId: listClientRegistrations
      tags:
        - Clients
      summary: List dynamically registered clients
      description: Filter with approval_state=pending, approved or rejected.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        client_ref:
                          type: string
                        client_id:
                          type: string
                        name:
                          type: string
                        client_type:
                          type: string
                        approval_state:
                          type: string
                        initial_token_id:
                          type: string
                        software_id:
                          type: string
                        software_version:
                          type: string
                        redirect_uris:
                          type: array
                          items:
                            type: string
                        created_at:
                          type: string
                          format: date-time
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/client-registrations/{client}/approve:
    post:
      operationId: approveClientRegistration
      tags:
        - Clients
      summary: Approve a pending registration
      description: Activates the client (audited client.registration.approved).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/client-registrations/{client}/reject:
    post:
      operationId: rejectClientRegistration
      tags:
        - Clients
      summary: Reject a pending registration
      description: Decommissions the client (audited client.registration.rejected).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_client'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/resource-types:
    get:
      operationId: listResourceTypes
      tags:
        - Authorization
      summary: List resource types
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resource_types.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResourceType'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/resource-types/{name}:
    get:
      operationId: getResourceType
      tags:
        - Authorization
      summary: Get a resource type
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resource_types.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_name'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceType'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: putResourceType
      tags:
        - Authorization
      summary: Register or replace a resource type
      description: >-
        AZ-022: services register their object types and permission schemas; the identity provider keeps relationships,
        never the objects. 201 when registered, 200 when replaced (If-Match required then: 428 without it, 412 when
        stale). Relations must be identifiers, implied_by must not form a cycle, permissions must be registered
        application permissions, link.relation needs a relation whose subjects are objects of another type,
        shareable_relations need a share_permission.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resource_types.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_name'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                resource_id:
                  type: string
                  description: The business resource (API) that owns the type.
                relations:
                  type: array
                  maxItems: 32
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      name:
                        type: string
                      subject_types:
                        type: array
                        items:
                          type: string
                        description: >-
                          user, service_principal, group, organization or a registered resource type (links such as
                          parent).
                      implied_by:
                        type: array
                        items:
                          type: string
                    required:
                      - name
                permissions:
                  type: object
                  additionalProperties:
                    type: array
                    items:
                      type: string
                  description: >-
                    Registered application permission -> relations that give it: relation, or link.relation through a
                    relation whose subjects are objects of another type.
                shareable_relations:
                  type: array
                  items:
                    type: string
                share_permission:
                  type: string
              required:
                - resource_id
                - relations
                - permissions
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceType'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteResourceType
      tags:
        - Authorization
      summary: Delete a resource type
      description: 409 while relationships use the type.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resource_types.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_name'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/relationships:
    post:
      operationId: writeRelationships
      tags:
        - Authorization
      summary: Write relationships
      description: >-
        AZ-021: adds and removes up to 100 tuples atomically in one active organization (audited as
        authorization.relationships.written). Subjects stay inside the organization: active members, its groups, the
        organization itself, service principals allowed in it, or objects of registered types. expires_at makes a tuple
        lapse on its own.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.relationships.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                writes:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      op:
                        type: string
                        enum:
                          - add
                          - remove
                      object_type:
                        type: string
                      object_id:
                        type: string
                        maxLength: 256
                      relation:
                        type: string
                      subject_type:
                        type: string
                      subject_id:
                        type: string
                      expires_at:
                        type: string
                        format: date-time
                    required:
                      - op
                      - object_type
                      - object_id
                      - relation
                      - subject_type
                      - subject_id
              required:
                - writes
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  writes:
                    type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: listRelationships
      tags:
        - Authorization
      summary: List relationships
      description: 'Filters: object_type, object_id, subject_type, subject_id; limit (1..500, default 100) and cursor.'
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.relationships.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        organization_id:
                          type: string
                        object_type:
                          type: string
                        object_id:
                          type: string
                        relation:
                          type: string
                        subject_type:
                          type: string
                        subject_id:
                          type: string
                        source:
                          type: string
                        expires_at:
                          type: string
                          format: date-time
                        created_by_id:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/authorization/list-objects:
    post:
      operationId: listAuthorizedObjects
      tags:
        - Authorization
      summary: List objects a subject may act on
      description: >-
        AZ-023: within one organization. all=true when an organization-wide grant (RBAC) covers the action; otherwise
        the objects of the type verified one by one through relationships, ordered by id after cursor. Never returns an
        unverified object; truncated=true when a bound was reached, also when an object's own evaluation reached one and
        it was left out. limit defaults to 100; a larger value than 500 is clamped to 500. Support tokens list read
        actions only.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.authorization.check
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                subject_token:
                  type: string
                  x-secret: true
                subject:
                  type: object
                  properties:
                    type:
                      type: string
                    id:
                      type: string
                action:
                  type: string
                resource:
                  type: object
                  properties:
                    type:
                      type: string
                    org_id:
                      type: string
                context:
                  type: object
                limit:
                  type: integer
                  minimum: 1
                  maximum: 500
                cursor:
                  type: string
              required:
                - action
                - resource
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  all:
                    type: boolean
                    description: True when an organization-wide grant covers the action for every object; objects is then empty.
                  objects:
                    type: array
                    items:
                      type: string
                  organization_id:
                    type: string
                  truncated:
                    type: boolean
                    description: A bound was reached; only verified objects are returned.
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/shares:
    post:
      operationId: offerShare
      tags:
        - Self-service
      summary: Offer to share an object
      description: >-
        AZ-027 user-managed sharing: the caller must hold the type's share_permission on the object; relation must be
        one of the type's shareable_relations; the recipient must be an active member of the same organization. The
        share is pending until the recipient accepts. Requires recent authentication.
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                organization_id:
                  type: string
                resource_type:
                  type: string
                object_id:
                  type: string
                relation:
                  type: string
                recipient_user_id:
                  type: string
                message:
                  type: string
                  maxLength: 500
                expires_at:
                  type: string
                  format: date-time
              required:
                - organization_id
                - resource_type
                - object_id
                - relation
                - recipient_user_id
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceShare'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: listShares
      tags:
        - Self-service
      summary: List shares
      description: >-
        direction=received (default) or sent; optional state. A pending or accepted share past its expires_at is listed,
        and filtered, as expired.
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResourceShare'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/shares/{id}/accept:
    post:
      operationId: acceptShare
      tags:
        - Self-service
      summary: Accept a share
      description: >-
        Creates the relationship tuple, after re-checking that the sharer may still share and the relation is still
        shareable. An offer past its expires_at is 409 and stored as expired.
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceShare'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/shares/{id}/decline:
    post:
      operationId: declineShare
      tags:
        - Self-service
      summary: Decline a share
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceShare'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/shares/{id}:
    delete:
      operationId: revokeShare
      tags:
        - Self-service
      summary: Revoke or give back a share
      description: The sharer withdraws an offer or access, or the recipient gives access back; the relationship tuple is removed.
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/elevation-eligibilities:
    post:
      operationId: createElevationEligibility
      tags:
        - Authorization
      summary: Make a person eligible for a role
      description: >-
        AZ-024: only someone who could assign the role at that scope (delegation ceiling) may create it, from an MFA
        session, and not for themselves. The person must be an active, non-guest user.
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                user_id:
                  type: string
                role_id:
                  type: string
                scope:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - realm
                        - organization
                        - project
                    id:
                      type: string
                max_duration_seconds:
                  type: integer
                  minimum: 300
                  maximum: 604800
                requires_approval:
                  type: boolean
                  description: Default true; privileged roles always require approval.
              required:
                - user_id
                - role_id
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElevationEligibility'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: listElevationEligibilities
      tags:
        - Authorization
      summary: List eligibilities
      description: Filter with user_id.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ElevationEligibility'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/elevation-eligibilities/{id}:
    delete:
      operationId: revokeElevationEligibility
      tags:
        - Authorization
      summary: Revoke an eligibility
      description: Pending requests under it are cancelled and an elevation in progress ends now.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.assign
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/elevations:
    get:
      operationId: listElevations
      tags:
        - Authorization
      summary: List elevation requests
      description: 'Filters: state (pending, active, rejected, ended, expired, cancelled), user_id.'
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Elevation'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/elevations/{id}/approve:
    post:
      operationId: approveElevation
      tags:
        - Authorization
      summary: Approve an elevation
      description: >-
        The approver must be able to assign the role at the scope and must not be the requester; users need recent
        authentication. The role is assigned (source elevation) until requested duration elapses from approval.
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Elevation'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/elevations/{id}/reject:
    post:
      operationId: rejectElevation
      tags:
        - Authorization
      summary: Reject an elevation
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Elevation'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/elevations/{id}/end:
    post:
      operationId: endElevation
      tags:
        - Authorization
      summary: End an elevation
      description: Ends an active elevation now (removing its assignment) or cancels a pending request.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.roles.assign
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/elevation-eligibilities:
    get:
      operationId: listMyElevationEligibilities
      tags:
        - Self-service
      summary: List my eligibilities
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ElevationEligibility'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/elevations:
    post:
      operationId: requestElevation
      tags:
        - Self-service
      summary: Ask for an elevation
      description: >-
        Needs a recent multi-factor session (403 step_up_required otherwise). Pending until approved when the
        eligibility requires approval, otherwise active at once. 409 while another request under the same eligibility is
        pending or active.
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                eligibility_id:
                  type: string
                duration_seconds:
                  type: integer
                  description: 300 up to the eligibility maximum (default the maximum).
                reason:
                  type: string
                  minLength: 3
                  maxLength: 500
              required:
                - eligibility_id
                - reason
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Elevation'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: listMyElevations
      tags:
        - Self-service
      summary: List my elevations
      description: Optional state filter.
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Elevation'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/elevations/{id}/end:
    post:
      operationId: endMyElevation
      tags:
        - Self-service
      summary: End my elevation
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/access-reviews:
    post:
      operationId: createAccessReview
      tags:
        - Authorization
      summary: Start an access review campaign
      description: >-
        AZ-025: snapshots up to 10000 role assignments in scope (filtered by roles and privilege) as items. Reviewers
        are active users who decide through /me/access-reviews.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.access_reviews.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  maxLength: 200
                description:
                  type: string
                  maxLength: 2000
                organization_id:
                  type: string
                  description: Review one organization's assignments; omitted for every assignment in the realm.
                reviewer_ids:
                  type: array
                  minItems: 1
                  maxItems: 20
                  items:
                    type: string
                role_ids:
                  type: array
                  items:
                    type: string
                privileged_only:
                  type: boolean
                on_no_decision:
                  type: string
                  enum:
                    - keep
                    - revoke
                due_at:
                  type: string
                  format: date-time
              required:
                - name
                - reviewer_ids
                - due_at
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessReview'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: listAccessReviews
      tags:
        - Authorization
      summary: List access review campaigns
      description: Optional state filter (open, closed, cancelled).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.access_reviews.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccessReview'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/access-reviews/{id}:
    get:
      operationId: getAccessReview
      tags:
        - Authorization
      summary: Get a campaign
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.access_reviews.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessReview'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/access-reviews/{id}/items:
    get:
      operationId: listAccessReviewItems
      tags:
        - Authorization
      summary: List campaign items
      description: 'decision filter: undecided, keep or revoke; limit (1..500) and cursor.'
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.access_reviews.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccessReviewItem'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/access-reviews/{id}/close:
    post:
      operationId: closeAccessReview
      tags:
        - Authorization
      summary: Close and apply a campaign
      description: >-
        Revokes items decided revoke (and undecided ones when on_no_decision is revoke) whose assignment still exists;
        records each outcome (kept, revoked, already_removed, revoke_failed — e.g. the last owner of an organization)
        and a summary. Campaigns past their due date are closed by the worker in the same way.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.access_reviews.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessReview'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/access-reviews/{id}/cancel:
    post:
      operationId: cancelAccessReview
      tags:
        - Authorization
      summary: Cancel a campaign
      description: Nothing is applied.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.access_reviews.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/access-reviews/{id}/evidence:
    get:
      operationId: exportAccessReviewEvidence
      tags:
        - Authorization
      summary: Export campaign evidence
      description: >-
        Every item with its decision, reviewer, time, comment and outcome. The export documents an access review; it is
        not a regulatory certification. Audited as access_review.evidence_exported.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.access_reviews.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  review:
                    $ref: '#/components/schemas/AccessReview'
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccessReviewItem'
                  generated_at:
                    type: string
                    format: date-time
                  statement:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/access-reviews:
    get:
      operationId: listMyAccessReviews
      tags:
        - Self-service
      summary: List campaigns I review
      description: state defaults to open.
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccessReview'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/access-reviews/{id}/items:
    get:
      operationId: listMyAccessReviewItems
      tags:
        - Self-service
      summary: List items of a campaign I review
      description: 404 unless the caller is one of the campaign's reviewers. Filters as for administrators.
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccessReviewItem'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/access-reviews/{id}/items/{item}/decision:
    post:
      operationId: decideAccessReviewItem
      tags:
        - Self-service
      summary: Decide an item
      description: >-
        Reviewers never decide on their own access (403). Decisions can change until the campaign closes (409
        afterwards).
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_item'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                decision:
                  type: string
                  enum:
                    - keep
                    - revoke
                comment:
                  type: string
                  maxLength: 1000
                  description: Required when revoking.
              required:
                - decision
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessReviewItem'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/certificate-trust-anchors:
    post:
      operationId: addCertificateTrustAnchor
      tags:
        - Clients
      summary: Trust a certificate authority
      description: >-
        MCH-014, PROV-016: client anchors (realm.clients.credentials) for mutual-TLS client authentication; user anchors
        (realm.settings.write) for X.509 sign-in. 409 while an active anchor already trusts the authority for that
        purpose (a removed anchor's authority can be added again, as a new anchor). With revocation crl, crl_pem must
        carry a nextUpdate; every certificate of the chain below the anchor is checked against its issuer's CRL, and a
        certificate issued by an intermediate (whose CRL the anchor does not hold) is refused.
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                purpose:
                  type: string
                  enum:
                    - client
                    - user
                name:
                  type: string
                  maxLength: 100
                certificate_pem:
                  type: string
                  description: Exactly one PEM CA certificate (basic constraints CA, not expired).
                revocation:
                  type: string
                  enum:
                    - none
                    - crl
                crl_pem:
                  type: string
                  description: >-
                    With revocation crl: a PEM X509 CRL signed by this authority; certificates are refused once it
                    passes its next update.
                map_san_email:
                  type: boolean
                  description: >-
                    User anchors: a certificate's single e-mail address signs in the account that verified that address,
                    without a binding.
                multi_factor:
                  type: boolean
                  description: >-
                    User anchors: the certificate key is protected by a second factor (smart card and PIN); sign-in
                    counts as phishing-resistant MFA.
              required:
                - purpose
                - name
                - certificate_pem
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateTrustAnchor'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: listCertificateTrustAnchors
      tags:
        - Clients
      summary: List trust anchors
      description: Optional purpose filter.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CertificateTrustAnchor'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/certificate-trust-anchors/{id}/crl:
    put:
      operationId: updateTrustAnchorCRL
      tags:
        - Clients
      summary: Replace a trust anchor CRL
      description: >-
        A newer CRL signed by the authority: a greater CRL number (or, when either list has none, a later thisUpdate),
        or the identical list again; an equal number with other content, an older list or a list without nextUpdate is
        422. Switches the anchor to revocation crl.
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                crl_pem:
                  type: string
              required:
                - crl_pem
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateTrustAnchor'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/certificate-trust-anchors/{id}:
    delete:
      operationId: removeCertificateTrustAnchor
      tags:
        - Clients
      summary: Stop trusting an authority
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/certificate-bindings:
    post:
      operationId: bindUserCertificate
      tags:
        - Users
      summary: Bind a certificate identity to an account
      description: >-
        PROV-016: certificates under the user anchor with this issuer and subject name sign in this account (a renewed
        certificate with the same names keeps working). A sample certificate_pem must be accepted by the anchor named in
        anchor_id (422 otherwise). MFA session required. 409 when the identity is bound to another account.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.credentials.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                anchor_id:
                  type: string
                issuer_dn:
                  type: string
                subject_dn:
                  type: string
                certificate_pem:
                  type: string
                  description: A sample certificate (verified against the anchor) instead of the names.
              required:
                - anchor_id
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateBinding'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: listUserCertificateBindings
      tags:
        - Users
      summary: List certificate bindings
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CertificateBinding'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/certificate-bindings/{id}:
    delete:
      operationId: unbindUserCertificate
      tags:
        - Users
      summary: Remove a certificate binding
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.credentials.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/auth/transactions/{id}/certificate:
    post:
      operationId: certificateStep
      tags:
        - Interaction
      summary: Sign in with an X.509 certificate
      description: >-
        PROV-016, only when the realm enables login.certificates (409 otherwise). The certificate comes from the TLS
        connection (send this step to the mutual-TLS endpoint) or a trusted proxy header, never from the body. It must
        chain to a user trust anchor, be valid and not revoked, and be bound to the account (or map by e-mail); when the
        transaction already names an account it must be that one. Failures count as failed proofs (400) and are audited
        as authentication.certificate.failed with a reason code.
      security:
        - transactionToken: []
        - transactionCookie: []
          csrfHeader: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionState'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/authentication-flow/revisions:
    get:
      operationId: listAuthFlowRevisions
      tags:
        - Authentication flows
      summary: List authentication-flow revisions
      description: AUT-019. Newest first, including drafts, published, superseded and discarded revisions.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuthFlowRevision'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createAuthFlowDraft
      tags:
        - Authentication flows
      summary: Save an authentication-flow draft
      description: >-
        AUT-019. Validates the definition, records the live flow it is based on and stores the reachability and bypass
        analysis. At most 20 open drafts.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - definition
              properties:
                definition:
                  $ref: '#/components/schemas/AuthFlowDefinition'
                note:
                  type: string
                  maxLength: 500
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthFlowRevision'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/authentication-flow/revisions/{revision}:
    get:
      operationId: getAuthFlowRevision
      tags:
        - Authentication flows
      summary: Get an authentication-flow revision
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_revision'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthFlowRevision'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: discardAuthFlowDraft
      tags:
        - Authentication flows
      summary: Discard an authentication-flow draft
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_revision'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/authentication-flow/revisions/{revision}/simulate:
    post:
      operationId: simulateAuthFlowRevision
      tags:
        - Authentication flows
      summary: Simulate a revision against the live flow
      description: AUT-019. Evaluates each case with the evaluator sign-in uses. An empty ip or risk is a missing signal.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_revision'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - cases
              properties:
                cases:
                  type: array
                  minItems: 1
                  maxItems: 200
                  items:
                    $ref: '#/components/schemas/AuthFlowCase'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - revision
                  - live_policy_revision
                  - results
                  - summary
                  - analysis
                properties:
                  revision:
                    type: integer
                  live_policy_revision:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                      required:
                        - case
                        - current
                        - candidate
                        - change
                      properties:
                        case:
                          type: string
                        current:
                          $ref: '#/components/schemas/AuthFlowResult'
                        candidate:
                          $ref: '#/components/schemas/AuthFlowResult'
                        change:
                          type: string
                          enum:
                            - unchanged
                            - stricter
                            - weaker
                            - rule_changed
                  summary:
                    type: object
                    additionalProperties:
                      type: integer
                  analysis:
                    $ref: '#/components/schemas/AuthFlowAnalysis'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/authentication-flow/revisions/{revision}/publish:
    post:
      operationId: publishAuthFlowRevision
      tags:
        - Authentication flows
      summary: Publish an authentication-flow draft
      description: >-
        AUT-019. Refuses (409) a draft whose base no longer matches the live flow, (422) a definition with bypass errors
        and (422) unacknowledged warnings. Advances the realm policy revision.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_revision'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                acknowledge_warnings:
                  type: boolean
                  description: Required when the analysis reports warnings.
                reason:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - revision
                  - policy_revision
                  - version
                properties:
                  revision:
                    $ref: '#/components/schemas/AuthFlowRevision'
                  policy_revision:
                    type: integer
                  version:
                    type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/authentication-flow/revisions/{revision}/rollback:
    post:
      operationId: rollbackAuthFlow
      tags:
        - Authentication flows
      summary: Republish an earlier revision
      description: AUT-019. Copies a previously published revision into a new revision and publishes it after analysing it again.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_revision'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                acknowledge_warnings:
                  type: boolean
                  description: Required when the analysis reports warnings.
                reason:
                  type: string
                  maxLength: 500
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - revision
                  - policy_revision
                  - version
                properties:
                  revision:
                    $ref: '#/components/schemas/AuthFlowRevision'
                  policy_revision:
                    type: integer
                  version:
                    type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /.well-known/ssf-configuration/realms/{realm}:
    get:
      operationId: ssfConfigurationWellKnown
      tags:
        - Shared signals
      summary: Shared Signals transmitter metadata (path-inserted form)
      description: >-
        AUD-016. Shared Signals Framework 1.0 transmitter metadata; 404 unless the realm policy sets
        shared_signals.enabled.
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFConfiguration'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/.well-known/ssf-configuration:
    get:
      operationId: ssfConfiguration
      tags:
        - Shared signals
      summary: Shared Signals transmitter metadata
      description: >-
        AUD-016. Shared Signals Framework 1.0 transmitter metadata; 404 unless the realm policy sets
        shared_signals.enabled.
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFConfiguration'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/ssf/streams:
    post:
      operationId: createSSFStream
      tags:
        - Shared signals
      summary: Create an event stream
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client. Poll streams get a transmitter-assigned endpoint_url. subject_scope all is reserved to administrators.
        At most 5 streams per receiver.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSFStreamInput'
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFStream'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: getSSFStreams
      tags:
        - Shared signals
      summary: Read one stream or list the caller's streams
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client. With stream_id, one stream; without, an array.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Query_stream_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SSFStream'
                  - type: array
                    items:
                      $ref: '#/components/schemas/SSFStream'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      operationId: updateSSFStream
      tags:
        - Shared signals
      summary: Update a stream
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client. Members not given are unchanged.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSFStreamInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFStream'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: replaceSSFStream
      tags:
        - Shared signals
      summary: Replace a stream configuration
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client. delivery and events_requested are required; read-only members may be echoed back.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSFStreamInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFStream'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteSSFStream
      tags:
        - Shared signals
      summary: Delete a stream
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client. Queued events are discarded.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Query_stream_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/ssf/streams/status:
    get:
      operationId: getSSFStreamStatus
      tags:
        - Shared signals
      summary: Read a stream status
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Query_stream_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - stream_id
                  - status
                properties:
                  stream_id:
                    type: string
                  status:
                    type: string
                    enum:
                      - enabled
                      - paused
                      - disabled
                  reason:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: setSSFStreamStatus
      tags:
        - Shared signals
      summary: Enable, pause or disable a stream
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client. A paused stream keeps queueing events and delivers them when enabled; disabling discards queued events.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - stream_id
                - status
              properties:
                stream_id:
                  type: string
                status:
                  type: string
                  enum:
                    - enabled
                    - paused
                    - disabled
                reason:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - stream_id
                  - status
                properties:
                  stream_id:
                    type: string
                  status:
                    type: string
                    enum:
                      - enabled
                      - paused
                      - disabled
                  reason:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/ssf/streams/subjects/add:
    post:
      operationId: addSSFSubject
      tags:
        - Shared signals
      summary: Add a subject to a stream
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client. Unknown subjects, and users who never authorized the receiver, are accepted without effect so the
        endpoint reveals nothing about accounts.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - stream_id
                - subject
              properties:
                stream_id:
                  type: string
                subject:
                  type: object
                  description: >-
                    A subject identifier (RFC 9493): {format: iss_sub, iss, sub} with sub as this client knows it
                    (pairwise included), or {format: email, email} for a verified address.
                  additionalProperties: true
                verified:
                  type: boolean
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/ssf/streams/subjects/remove:
    post:
      operationId: removeSSFSubject
      tags:
        - Shared signals
      summary: Remove a subject from a stream
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - stream_id
                - subject
              properties:
                stream_id:
                  type: string
                subject:
                  type: object
                  description: >-
                    A subject identifier (RFC 9493): {format: iss_sub, iss, sub} with sub as this client knows it
                    (pairwise included), or {format: email, email} for a verified address.
                  additionalProperties: true
                verified:
                  type: boolean
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/ssf/streams/verify:
    post:
      operationId: verifySSFStream
      tags:
        - Shared signals
      summary: Request a verification event
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client. At most once per min_verification_interval (60 s; 429 otherwise).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - stream_id
              properties:
                stream_id:
                  type: string
                state:
                  type: string
                  maxLength: 256
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/ssf/streams/{id}/poll:
    post:
      operationId: pollSSFStream
      tags:
        - Shared signals
      summary: Poll for Security Event Tokens (RFC 8936)
      description: >-
        AUD-016. Callable by a machine client (client-credentials token for the admin API) holding
        realm.ssf_streams.manage, on a realm with shared_signals.enabled (404 otherwise). Streams belong to the calling
        client. Acknowledges (ack) or rejects (setErrs) earlier tokens, then returns up to maxEvents (default 50, at
        most 100) outstanding tokens. Unacknowledged tokens are returned again, unchanged. Responds immediately.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                ack:
                  type: array
                  maxItems: 1000
                  items:
                    type: string
                setErrs:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      err:
                        type: string
                      description:
                        type: string
                maxEvents:
                  type: integer
                  minimum: 0
                returnImmediately:
                  type: boolean
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - sets
                  - moreAvailable
                properties:
                  sets:
                    type: object
                    description: Security Event Tokens keyed by jti.
                    additionalProperties:
                      type: string
                  moreAvailable:
                    type: boolean
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/ssf-streams:
    get:
      operationId: listSSFStreamsAdmin
      tags:
        - Shared signals
      summary: List every shared-signals stream
      description: AUD-016.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SSFStream'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/ssf-streams/{id}:
    get:
      operationId: getSSFStreamAdmin
      tags:
        - Shared signals
      summary: Get a stream
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFStream'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      operationId: updateSSFStreamAdmin
      tags:
        - Shared signals
      summary: Change a stream subject scope
      description: >-
        AUD-016. Only administrators can set all (events about every user of the realm); the receiver cannot change it
        back.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                subject_scope:
                  type: string
                  enum:
                    - client_users
                    - listed
                    - all
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFStream'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteSSFStreamAdmin
      tags:
        - Shared signals
      summary: Delete a stream
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/ssf-streams/{id}/status:
    post:
      operationId: setSSFStreamStatusAdmin
      tags:
        - Shared signals
      summary: Change a stream status
      description: AUD-016. The receiver is sent a stream-updated event.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - status
              properties:
                status:
                  type: string
                  enum:
                    - enabled
                    - paused
                    - disabled
                reason:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFStream'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/ssf-streams/{id}/events:
    get:
      operationId: listSSFStreamEvents
      tags:
        - Shared signals
      summary: List a stream's recent events
      description: AUD-016. Delivery state of the newest 200 events; tokens are not returned.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.ssf_streams.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        jti:
                          type: string
                        event_type:
                          type: string
                        state:
                          type: string
                          enum:
                            - pending
                            - delivered
                            - acknowledged
                            - failed
                            - expired
                        attempts:
                          type: integer
                        occurred_at:
                          type: string
                          format: date-time
                        delivered_at:
                          type: string
                          format: date-time
                        last_status_code:
                          type: integer
                        last_error:
                          type: string
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/saml/metadata:
    get:
      operationId: getSAMLIdentityProviderMetadata
      tags:
        - SAML
      summary: SAML identity provider metadata
      description: >-
        Realm IdP metadata (SAML-001, SAML-005): entityID is the realm issuer; HTTP-Redirect and HTTP-POST
        SingleSignOnService and SingleLogoutService at /saml/sso and /saml/slo; NameIDFormat persistent, emailAddress,
        unspecified and transient; every published signing certificate (KeyDescriptor use=signing): the next key before
        it signs and the previous key while it retires (SAML-002). No artifact binding, no encryption key, no attribute
        authority. Unsigned (served over TLS). Cacheable for 300 seconds. Returns 404 feature_disabled unless
        saml.enabled.
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Cache-Control:
              schema:
                type: string
              description: public, max-age=300
          content:
            application/samlmetadata+xml:
              schema:
                type: string
                description: md:EntityDescriptor with an IDPSSODescriptor.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/saml/sso:
    get:
      operationId: samlSingleSignOnRedirect
      tags:
        - SAML
      summary: SAML single sign-on (HTTP-Redirect)
      description: >-
        Single sign-on (HTTP-Redirect binding): AuthnRequest in SAMLRequest (DEFLATE + base64) with RelayState and, when
        signed, SigAlg and Signature over the received query octets. Validated before anything is sent anywhere (local
        400 problem with extension reason): issuer is a registered SAML application (saml_unknown_service_provider),
        signature with the application's registered certificates when present or required (saml_signature;
        RSA-SHA256/384/512 only, SHA-1 refused), Version 2.0, IssueInstant within the application's skew and not older
        than 10 minutes, Destination equal to this endpoint when present, AssertionConsumerServiceURL registered exactly
        (or a registered index, or the default ACS) with the HTTP-POST binding (saml_unregistered_acs), each request ID
        once (saml_request_replay), DTD/entities/comments/oversized messages refused (saml_invalid_request). Requests
        the IdP cannot honor are answered with a signed SAML error Response to the validated ACS (200 HTML form):
        unsupported NameIDPolicy Format (InvalidNameIDPolicy), unknown or unsatisfiable RequestedAuthnContext
        (NoAuthnContext), a Subject (RequestUnsupported), IsPassive with ForceAuthn (NoPassive). Accepted requests set
        the pa_saml browser-binding cookie and run the realm's authentication transaction for the application's backing
        client: an SSO session (pa_sid) is reused unless ForceAuthn; IsPassive never shows a login page; requested MFA
        contexts require step-up. Results: 302 to the login interface (with pa_tx), 200 auto-submitting form to the ACS
        when the session completes silently. Returns 404 feature_disabled unless saml.enabled.
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: SAMLRequest
          in: query
          required: false
          schema:
            type: string
          description: DEFLATE-compressed, base64-encoded AuthnRequest.
        - name: RelayState
          in: query
          required: false
          schema:
            type: string
          description: Opaque service provider state, returned unchanged (at most 1024 bytes).
        - name: SigAlg
          in: query
          required: false
          schema:
            type: string
          description: Signature algorithm URI (rsa-sha256, rsa-sha384 or rsa-sha512).
        - name: Signature
          in: query
          required: false
          schema:
            type: string
          description: Base64 signature over SAMLRequest, RelayState and SigAlg as received.
      responses:
        '200':
          description: SAML Response (success or error status) posted to the validated assertion consumer service.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Content-Security-Policy:
              schema:
                type: string
              description: default-src 'none'; script-src 'nonce-<per response>'; frame-ancestors 'none'; base-uri 'none'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            text/html:
              schema:
                type: string
                description: >-
                  Auto-submitting HTML form (SAMLResponse and RelayState hidden inputs) with a no-script Continue
                  button.
        '302':
          description: Redirect to the login interface with transaction_id (sets pa_tx and pa_saml).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: samlSingleSignOnPost
      tags:
        - SAML
      summary: SAML single sign-on (HTTP-POST)
      description: >-
        HTTP-POST binding: base64 AuthnRequest in SAMLRequest, optionally with an enveloped XML signature (required when
        the application requires signed requests; Destination is then mandatory). Validation as for the HTTP-Redirect
        binding. A cross-site form post carries no SameSite=Lax cookies, so an accepted request is continued by a 303 to
        GET /saml/sso/continue?request=..., which does. Returns 404 feature_disabled unless saml.enabled.
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              description: Size-bounded by saml.max_message_bytes.
              properties:
                SAMLRequest:
                  type: string
                  description: Base64-encoded AuthnRequest.
                RelayState:
                  type: string
                  description: Opaque service provider state (at most 1024 bytes).
              required:
                - SAMLRequest
      responses:
        '200':
          description: SAML error Response posted to the validated assertion consumer service.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Content-Security-Policy:
              schema:
                type: string
              description: default-src 'none'; script-src 'nonce-<per response>'; frame-ancestors 'none'; base-uri 'none'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            text/html:
              schema:
                type: string
                description: >-
                  Auto-submitting HTML form (SAMLResponse and RelayState hidden inputs) with a no-script Continue
                  button.
        '303':
          description: Continue at GET /saml/sso/continue?request=... (sets pa_saml).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/saml/sso/continue:
    get:
      operationId: samlSingleSignOnContinue
      tags:
        - SAML
      summary: Continue or complete SAML single sign-on
      description: >-
        With request: starts the recorded request in this browser (pa_saml must match). With code and state (or error
        and state): the authentication transaction's completion, addressed to this endpoint; the request is consumed
        once, only by the browser holding its pa_saml binding secret; the internal authorization code is redeemed here
        with the server-held PKCE verifier and must belong to the request's transaction and the application's backing
        client. Then a signed Response is posted to the ACS: bearer SubjectConfirmation (Recipient, InResponseTo,
        NotOnOrAfter), audience restriction, AuthnStatement with SessionIndex and AuthnContextClassRef, the mapped
        attributes. Errors: RequestDenied (cancelled, organization membership missing, emergency switch), NoPassive,
        NoAuthnContext, InvalidNameIDPolicy (no verified email for emailAddress), AuthnFailed. A missing or foreign
        binding cookie, replay or expiry gives 400 transaction_invalid (reason saml_request_invalid). Returns 404
        feature_disabled unless saml.enabled.
      security: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: request
          in: query
          required: false
          schema:
            type: string
          description: Recorded request reference (sir_...).
        - name: code
          in: query
          required: false
          schema:
            type: string
            x-secret: true
          description: Internal authorization code.
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: Request state.
        - name: error
          in: query
          required: false
          schema:
            type: string
          description: Transaction error (access_denied, ...).
        - name: iss
          in: query
          required: false
          schema:
            type: string
          description: Issuer (ignored).
      responses:
        '200':
          description: SAML Response posted to the request's assertion consumer service.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Content-Security-Policy:
              schema:
                type: string
              description: default-src 'none'; script-src 'nonce-<per response>'; frame-ancestors 'none'; base-uri 'none'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            text/html:
              schema:
                type: string
                description: >-
                  Auto-submitting HTML form (SAMLResponse and RelayState hidden inputs) with a no-script Continue
                  button.
        '302':
          description: Redirect to the login interface with transaction_id (sets pa_tx).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/saml/idp-initiated:
    get:
      operationId: samlIdPInitiatedSignOn
      tags:
        - SAML
      summary: IdP-initiated SAML sign-on
      description: >-
        Unsolicited sign-in to sp (entity ID or application ID), refused with 403 (reason saml_unsolicited_disabled)
        unless the application sets allow_idp_initiated (SAML-007). Policy: the destination is always the application's
        default ACS, RelayState is only the registered idp_initiated_relay_state (never taken from the request), the
        Response carries no InResponseTo, the assertion is bound to this browser (pa_saml) and each use is audited.
        Returns 404 feature_disabled unless saml.enabled.
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: sp
          in: query
          required: false
          schema:
            type: string
          description: Service provider entity ID or SAML application ID.
      responses:
        '200':
          description: SAML Response posted to the default assertion consumer service.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Content-Security-Policy:
              schema:
                type: string
              description: default-src 'none'; script-src 'nonce-<per response>'; frame-ancestors 'none'; base-uri 'none'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            text/html:
              schema:
                type: string
                description: >-
                  Auto-submitting HTML form (SAMLResponse and RelayState hidden inputs) with a no-script Continue
                  button.
        '302':
          description: Redirect to the login interface with transaction_id (sets pa_tx and pa_saml).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/saml/slo:
    get:
      operationId: samlSingleLogoutRedirect
      tags:
        - SAML
      summary: SAML single logout (HTTP-Redirect)
      description: >-
        Single logout (SAML-008), declared subset: SP-initiated LogoutRequest only, always signed with a registered key
        of the issuing application (HTTP-Redirect detached signature or HTTP-POST enveloped signature), Destination
        equal to this endpoint when present, IssueInstant within skew, NotOnOrAfter honored. The NameID (and
        SessionIndex values, or all of that subject's sessions with the application) select IdP sessions the application
        received assertions for; they end with their grants and refresh tokens (OIDC clients with back-channel logout
        are notified). The signed LogoutResponse goes to the application's registered logout endpoint in its binding,
        with status Success, and second-level PartialLogout when other SAML applications or OIDC clients without
        back-channel logout took part in the session and were not notified. The browser's pa_sid is cleared when its
        session ended. LogoutResponses (IdP-initiated logout) are not implemented and refused with 400. Returns 404
        feature_disabled unless saml.enabled.
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: SAMLRequest
          in: query
          required: false
          schema:
            type: string
          description: DEFLATE-compressed, base64-encoded LogoutRequest.
        - name: RelayState
          in: query
          required: false
          schema:
            type: string
          description: Opaque state, returned unchanged.
        - name: SigAlg
          in: query
          required: false
          schema:
            type: string
          description: Signature algorithm URI.
        - name: Signature
          in: query
          required: false
          schema:
            type: string
          description: Base64 signature over the query as received.
      responses:
        '200':
          description: Signed LogoutResponse posted to an HTTP-POST logout endpoint.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Content-Security-Policy:
              schema:
                type: string
              description: default-src 'none'; script-src 'nonce-<per response>'; frame-ancestors 'none'; base-uri 'none'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            text/html:
              schema:
                type: string
                description: >-
                  Auto-submitting HTML form (SAMLResponse and RelayState hidden inputs) with a no-script Continue
                  button.
        '302':
          description: Signed LogoutResponse to an HTTP-Redirect logout endpoint (clears pa_sid when that session ended).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: samlSingleLogoutPost
      tags:
        - SAML
      summary: SAML single logout (HTTP-POST)
      description: >-
        Single logout (SAML-008), declared subset: SP-initiated LogoutRequest only, always signed with a registered key
        of the issuing application (HTTP-Redirect detached signature or HTTP-POST enveloped signature), Destination
        equal to this endpoint when present, IssueInstant within skew, NotOnOrAfter honored. The NameID (and
        SessionIndex values, or all of that subject's sessions with the application) select IdP sessions the application
        received assertions for; they end with their grants and refresh tokens (OIDC clients with back-channel logout
        are notified). The signed LogoutResponse goes to the application's registered logout endpoint in its binding,
        with status Success, and second-level PartialLogout when other SAML applications or OIDC clients without
        back-channel logout took part in the session and were not notified. The browser's pa_sid is cleared when its
        session ended. LogoutResponses (IdP-initiated logout) are not implemented and refused with 400. Returns 404
        feature_disabled unless saml.enabled.
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              description: Size-bounded by saml.max_message_bytes.
              properties:
                SAMLRequest:
                  type: string
                  description: Base64-encoded, enveloped-signed LogoutRequest.
                RelayState:
                  type: string
                  description: Opaque state.
              required:
                - SAMLRequest
      responses:
        '200':
          description: Signed LogoutResponse posted to an HTTP-POST logout endpoint.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Content-Security-Policy:
              schema:
                type: string
              description: default-src 'none'; script-src 'nonce-<per response>'; frame-ancestors 'none'; base-uri 'none'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
          content:
            text/html:
              schema:
                type: string
                description: >-
                  Auto-submitting HTML form (SAMLResponse and RelayState hidden inputs) with a no-script Continue
                  button.
        '302':
          description: Signed LogoutResponse to an HTTP-Redirect logout endpoint.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/saml/sp/{connection}:
    get:
      operationId: getSAMLServiceProviderMetadata
      tags:
        - SAML
      summary: SAML service provider metadata of a connection
      description: >-
        This realm's service provider metadata for a SAML connection (FED-014): entityID (the connection's sp_entity_id,
        default this URL), AuthnRequestsSigned, WantAssertionsSigned=true, the realm SAML signing certificates (next key
        included), the requested NameIDFormat and the HTTP-POST AssertionConsumerService at /saml/acs/{connection}. No
        SingleLogoutService: upstream SAML sessions are not ended by the broker. Returns 404 feature_disabled unless
        saml.enabled and federation.enabled.
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_connection'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Cache-Control:
              schema:
                type: string
              description: public, max-age=300
          content:
            application/samlmetadata+xml:
              schema:
                type: string
                description: md:EntityDescriptor with an SPSSODescriptor.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /realms/{realm}/saml/acs/{connection}:
    post:
      operationId: samlAssertionConsumerService
      tags:
        - SAML
      summary: SAML assertion consumer service (HTTP-POST)
      description: >-
        Receives a connection's SAML Response (FED-014). Unsolicited responses (no InResponseTo), unknown, replayed or
        expired requests, a RelayState that does not match the request's secret, and unparseable or unsafe XML (DTD,
        entities, comments, processing instructions, duplicate IDs, oversized) are refused with 400 invalid_proof before
        any transaction is touched. Otherwise the request is consumed once and the response validated (SAML-003,
        SAML-004, SAML-009): Success status; exactly one Assertion, a direct child, no EncryptedAssertion; a valid
        RSA-SHA256+ signature by a trusted connection certificate over the assertion or the response (overlapping
        certificates for rollover), values read only from the signed element; Destination = this ACS and InResponseTo =
        the request; Issuer = the connection's IdP entity ID; IssueInstant, Conditions NotBefore/NotOnOrAfter within the
        connection's skew; every AudienceRestriction contains the SP entity ID; no unknown condition; a bearer
        SubjectConfirmation with Recipient = this ACS, InResponseTo = the request and a live NotOnOrAfter;
        AuthnStatement present and SessionNotOnOrAfter not passed; the assertion ID not seen before (replay). The
        identity then goes through the federation linking, JIT and organization rules. The outcome is reported like an
        OIDC callback: 303 to the login interface with transaction_id (federation_error on failure), or JSON for
        headless realms. Returns 404 feature_disabled unless saml.enabled and federation.enabled.
      security: []
      x-trust-class: transaction-bound
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_connection'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              description: Size-bounded by saml.max_message_bytes.
              properties:
                SAMLResponse:
                  type: string
                  description: Base64-encoded Response.
                RelayState:
                  type: string
                  description: The RelayState sent with the AuthnRequest.
              required:
                - SAMLResponse
                - RelayState
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: CallbackOutcome
                    properties:
                      transaction_id:
                        type: string
                      status:
                        type: string
                        enum:
                          - ok
                          - error
                      error:
                        type: string
                        description: >-
                          upstream_invalid_response, upstream_denied, account_conflict, no_linked_account,
                          email_domain_not_allowed, account_unavailable, account_mismatch, connection_disabled (the
                          connection was disabled while the user was at the upstream).
                    required:
                      - status
                  - type: object
                    title: LinkPendingConfirmation
                    properties:
                      status:
                        type: string
                        const: link_pending_confirmation
                      link_code:
                        type: string
                        x-secret: true
                        description: Single-use code for POST /me/linked-identities/confirm.
                    required:
                      - status
                      - link_code
        '303':
          description: Redirect to the realm login UI.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Location:
              $ref: '#/components/headers/Location'
            Set-Cookie:
              $ref: '#/components/headers/Set-Cookie'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/saml/applications:
    get:
      operationId: listSAMLApplications
      tags:
        - SAML
      summary: List SAML applications
      description: Registered service providers of the realm (APP-018). Returns 404 feature_disabled unless saml.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SAMLApplication'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createSAMLApplication
      tags:
        - SAML
      summary: Register a SAML application
      description: >-
        Registers a service provider and its backing client (protocol saml). metadata_xml (uploaded SPSSODescriptor
        metadata; never fetched from a URL) fills entity ID, HTTP-POST ACS, logout endpoints and signing certificates
        that are not given explicitly. Validation (422): entity ID an absolute URI; 1..10 HTTP-POST ACS URLs with
        exact-redirect rules (https outside development, no fragment, userinfo, wildcard or traversal); 0..4 logout
        endpoints (HTTP-Redirect or HTTP-POST), which need a signing certificate; signing certificates RSA >= 2048 bits,
        not expired, at most 4 (overlap for rollover); encrypt_assertions needs an RSA >= 2048 encryption certificate
        (explicit, or the metadata's encryption key) and allows only aes256-gcm/aes128-gcm content and
        rsa-oaep-mgf1p/xmlenc11 rsa-oaep key transport (CBC and RSA 1.5 refused); an encryption certificate without
        encrypt_assertions is refused; signature_algorithm rsa-sha256 (default), rsa-sha384 or rsa-sha512; at least one
        of sign_response / sign_assertion; attribute sources from the fixed list, static values never under protected
        identity names (email names carry only the verified email, identifier names only user_id, subject, email or
        preferred_username); clock_skew_seconds <= saml.max_clock_skew; assertion_lifetime_seconds 60..1800;
        authn_context_map values are local ACRs. 409 when the entity ID is registered. Returns 404 feature_disabled
        unless saml.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SAMLApplicationInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SAMLApplication'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/saml/applications/{id}:
    get:
      operationId: getSAMLApplication
      tags:
        - SAML
      summary: Get a SAML application
      description: Returns 404 feature_disabled unless saml.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SAMLApplication'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      operationId: replaceSAMLApplication
      tags:
        - SAML
      summary: Replace a SAML application
      description: >-
        Replaces the application and its backing client's name, consent and assurance settings; the environment is
        fixed. Certificate, attribute and IdP-initiated changes are audited (saml.application.updated). Returns 404
        feature_disabled unless saml.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchRequired'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SAMLApplicationInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SAMLApplication'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteSAMLApplication
      tags:
        - SAML
      summary: Delete a SAML application
      description: >-
        Removes the application (its pending requests and logout records) and decommissions the backing client, which
        revokes its grants. The entity ID can then be registered again. Suspend an application instead with POST
        /clients/{client_ref}/suspend. Returns 404 feature_disabled unless saml.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.clients.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/saml/connections:
    get:
      operationId: listSAMLConnections
      tags:
        - SAML
      summary: List SAML connections
      description: >-
        Upstream SAML identity providers of the realm (FED-014). Returns 404 feature_disabled unless saml.enabled and
        federation.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SAMLConnection'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: createSAMLConnection
      tags:
        - SAML
      summary: Create a SAML connection
      description: >-
        Creates an identity_providers connection of kind saml. metadata_xml (uploaded IDPSSODescriptor metadata; never
        fetched) fills the IdP entity ID, the HTTP-Redirect SSO endpoint and the signing certificates that are not given
        explicitly. Validation (422): IdP entity ID an absolute URI; sso_url https (http only outside production); at
        least one trusted signing certificate (RSA >= 2048, not expired, at most 4 for overlap); a transient
        name_id_format needs subject_attribute; trust_upstream_mfa needs trusted_authn_contexts; trusted_verified_email
        linking needs trust_email_verified and allowed_email_domains; jit_default_role_id needs organization_id and must
        be assignable by the caller; clock_skew_seconds <= saml.max_clock_skew. Certificate fingerprints are audited
        (federation.provider.created). Returns 404 feature_disabled unless saml.enabled and federation.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SAMLConnectionInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SAMLConnection'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/saml/connections/{id}:
    get:
      operationId: getSAMLConnection
      tags:
        - SAML
      summary: Get a SAML connection
      description: >-
        The connection, its trusted certificates (with fingerprints and validity) and this realm's service provider
        endpoints to register with the IdP. Returns 404 feature_disabled unless saml.enabled and federation.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SAMLConnection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      operationId: replaceSAMLConnection
      tags:
        - SAML
      summary: Replace a SAML connection
      description: >-
        alias cannot change; the IdP entity ID cannot change while identities are linked (409). Certificate rollover:
        list the current and the next certificate together (both are trusted), then remove the old one; added and
        removed fingerprints are audited (federation.provider.updated, SAML-002). Returns 404 feature_disabled unless
        saml.enabled and federation.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IfMatchRequired'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SAMLConnectionInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SAMLConnection'
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: deleteSAMLConnection
      tags:
        - SAML
      summary: Delete a SAML connection
      description: >-
        Deletes a connection without linked identities (409 otherwise: disable it instead), with its pending requests
        and replay records. Returns 404 feature_disabled unless saml.enabled and federation.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/saml/signing-keys:
    get:
      operationId: listSAMLSigningKeys
      tags:
        - SAML
      summary: List SAML signing keys
      description: >-
        The realm's SAML signing keys (RSA, self-signed certificates), separate from the JWT signing keys: state pending
        (published next key), active, retiring (published until publish_until) or retired, and whether each is currently
        published in metadata. Public certificates only. The first key is created on first use. Returns 404
        feature_disabled unless saml.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.keys.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SAMLSigningKey'
                required:
                  - items
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: prepareSAMLSigningKey
      tags:
        - SAML
      summary: Publish the next SAML signing key
      description: >-
        Creates the next key in state pending: published in IdP and SP metadata at once, signing nothing until activated
        (controlled rollover, SAML-002). 409 when a next key is already published. Returns 404 feature_disabled unless
        saml.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.keys.rotate
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SAMLSigningKey'
        '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'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/saml/signing-keys/{id}/activate:
    post:
      operationId: activateSAMLSigningKey
      tags:
        - SAML
      summary: Activate the next SAML signing key
      description: >-
        Promotes the pending key to active; the previous active key retires and stays published for
        saml.retired_key_publication. Refused (409) until the key has been published for saml.key_prepublish, unless
        force is set with a reason (422 without one). Returns 404 feature_disabled unless saml.enabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.keys.rotate
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                force:
                  type: boolean
                  description: >-
                    Activate before saml.key_prepublish has elapsed (an emergency; needs a reason of at least 10
                    characters; audited in the emergency category).
                reason:
                  type: string
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SAMLSigningKey'
                required:
                  - items
        '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'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/realms/{realm}/directory-connectors:
    get:
      operationId: listRealmDirectoryConnectors
      tags:
        - Directory
      summary: List directory and outbound connectors
      description: >-
        Lists LDAP/Active Directory connectors (kind ldap) and outbound SCIM connectors (kind scim_outbound).
        Credentials are never returned (credential_set only). Realm administration: every connector of the realm,
        realm-wide (workforce) and organization-bound. Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.read
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/DirectoryConnector'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createRealmDirectoryConnector
      tags:
        - Directory
      summary: Create a directory or outbound connector
      description: >-
        Creates a connector with its write-only credential (the service-account bind password for ldap, the downstream
        bearer token for scim_outbound), stored encrypted. Organization connectors' role ceiling must lie within the
        creator's own ceiling and group mappings within the ceiling (PROV-003, PROV-007, TEST-049); realm connectors
        grant no roles or memberships (FED-015). LDAP endpoints must use ldaps:// or StartTLS outside development;
        outbound destinations pass the egress policy (EXT-007). The realm API may bind the connector to an organization
        with organization_id. Realm administration: every connector of the realm, realm-wide (workforce) and
        organization-bound. Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectoryConnectorInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryConnector'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/directory-connectors/{id}:
    get:
      operationId: getRealmDirectoryConnector
      tags:
        - Directory
      summary: Get a directory or outbound connector
      description: >-
        Returns the connector definition with last_sync_at, last_success_at, last_error and consecutive_failures
        (PROV-018). Realm administration: every connector of the realm, realm-wide (workforce) and organization-bound.
        Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.read
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryConnector'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateRealmDirectoryConnector
      tags:
        - Directory
      summary: Update a directory or outbound connector
      description: >-
        Replaces the definition (not the credential; use PUT .../credential); kind and organization are fixed. state
        disabled stops runs and deliveries at once and fails directory sign-in of the connector's accounts closed
        (upstream_unavailable). Requires If-Match. Realm administration: every connector of the realm, realm-wide
        (workforce) and organization-bound. Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchRequired'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectoryConnectorUpdate'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryConnector'
        '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/UnprocessableEntity'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteRealmDirectoryConnector
      tags:
        - Directory
      summary: Delete a disabled connector
      description: >-
        Deletes a connector that was disabled first (409 otherwise), with its links, runs and deliveries. Accounts stay;
        their owners recover sign-in through the realm's recovery methods. Realm administration: every connector of the
        realm, realm-wide (workforce) and organization-bound. Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: Deleted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/directory-connectors/{id}/credential:
    put:
      operationId: setRealmDirectoryConnectorCredential
      tags:
        - Directory
      summary: Replace the connector credential
      description: >-
        Replaces the encrypted bind password or bearer token; the previous one is never used again. The credential is
        write-only. Realm administration: every connector of the realm, realm-wide (workforce) and organization-bound.
        Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                credential:
                  type: string
                  minLength: 1
                  maxLength: 4096
                  x-secret: true
              required:
                - credential
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryConnector'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/directory-connectors/{id}/test:
    post:
      operationId: testRealmDirectoryConnector
      tags:
        - Directory
      summary: Test a connector
      description: >-
        Connects, negotiates TLS and binds as the service account (ldap), or reads the downstream ServiceProviderConfig
        (scim_outbound). Changes nothing; recorded as an operator action (PROV-018). Realm administration: every
        connector of the realm, realm-wide (workforce) and organization-bound. Requires an administration token and an
        MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryTestResult'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/directory-connectors/{id}/runs:
    get:
      operationId: listRealmDirectoryRuns
      tags:
        - Directory
      summary: List synchronization and reconciliation runs
      description: >-
        Newest first (PROV-012, PROV-017). Realm administration: every connector of the realm, realm-wide (workforce)
        and organization-bound. Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.read
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/DirectoryRun'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: requestRealmDirectoryRun
      tags:
        - Directory
      summary: Request a run
      description: >-
        Queues a full or incremental directory synchronization, or an outbound reconciliation, as a job; at most one run
        of a connector is queued or running (409 with run_id). dry_run computes the plan with the same logic and changes
        nothing. allow_mass_deprovision overrides the deletion threshold for one applied full run and needs a reason; it
        is audited. Realm administration: every connector of the realm, realm-wide (workforce) and organization-bound.
        Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectoryRunRequest'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryRun'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/directory-connectors/{id}/runs/{run}:
    get:
      operationId: getRealmDirectoryRun
      tags:
        - Directory
      summary: Get a run
      description: >-
        State, counts, cursors and the endpoint used. Realm administration: every connector of the realm, realm-wide
        (workforce) and organization-bound. Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.read
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_run'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryRun'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/directory-connectors/{id}/runs/{run}/findings:
    get:
      operationId: listRealmDirectoryRunFindings
      tags:
        - Directory
      summary: List a run's findings
      description: >-
        Plan items, applied changes, conflicts, divergences and errors of a run (at most 5000 stored per run; counts
        stay complete). Page with after=next_after. Realm administration: every connector of the realm, realm-wide
        (workforce) and organization-bound. Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.read
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_run'
        - $ref: '#/components/parameters/DirectoryFindingKind'
        - $ref: '#/components/parameters/DirectoryFindingsAfter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/DirectoryFinding'
                  next_after:
                    type: string
                    description: Pass as after for the next page; empty on the last page.
                required:
                  - items
                  - next_after
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/directory-connectors/{id}/health:
    get:
      operationId: getRealmDirectoryConnectorHealth
      tags:
        - Directory
      summary: Connector operational evidence
      description: >-
        Health status, last successful run, lag, endpoint health, managed record counts, outbound backlog and the latest
        operator actions (PROV-018). Never contains credentials. Realm administration: every connector of the realm,
        realm-wide (workforce) and organization-bound. Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.read
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryHealth'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/directory-connectors/{id}/deliveries:
    get:
      operationId: listRealmOutboundDeliveries
      tags:
        - Directory
      summary: List outbound deliveries
      description: >-
        Outbound provisioning deliveries (scim_outbound connectors), newest first; no payloads or credentials. Realm
        administration: every connector of the realm, realm-wide (workforce) and organization-bound. Requires an
        administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.read
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/OutboundDeliveryState'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/OutboundDelivery'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/directory-connectors/{id}/deliveries/{delivery}/replay:
    post:
      operationId: replayRealmOutboundDelivery
      tags:
        - Directory
      summary: Replay a dead-lettered delivery
      description: >-
        Re-opens a dead-lettered delivery as a fresh attempt series (409 for other states); recorded as an operator
        action. Realm administration: every connector of the realm, realm-wide (workforce) and organization-bound.
        Requires an administration token and an MFA session.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.provisioning.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_outbound_delivery'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/directory-connectors:
    get:
      operationId: listOrgDirectoryConnectors
      tags:
        - Directory
      summary: List directory and outbound connectors
      description: >-
        Lists LDAP/Active Directory connectors (kind ldap) and outbound SCIM connectors (kind scim_outbound).
        Credentials are never returned (credential_set only). Organization scope: only the organization's own connectors
        are visible (others return 404).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/DirectoryConnector'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createOrgDirectoryConnector
      tags:
        - Directory
      summary: Create a directory or outbound connector
      description: >-
        Creates a connector with its write-only credential (the service-account bind password for ldap, the downstream
        bearer token for scim_outbound), stored encrypted. Organization connectors' role ceiling must lie within the
        creator's own ceiling and group mappings within the ceiling (PROV-003, PROV-007, TEST-049); realm connectors
        grant no roles or memberships (FED-015). LDAP endpoints must use ldaps:// or StartTLS outside development;
        outbound destinations pass the egress policy (EXT-007). Organization scope: only the organization's own
        connectors are visible (others return 404). Changes require an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectoryConnectorInput'
      responses:
        '201':
          description: Created
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryConnector'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/directory-connectors/{id}:
    get:
      operationId: getOrgDirectoryConnector
      tags:
        - Directory
      summary: Get a directory or outbound connector
      description: >-
        Returns the connector definition with last_sync_at, last_success_at, last_error and consecutive_failures
        (PROV-018). Organization scope: only the organization's own connectors are visible (others return 404).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryConnector'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateOrgDirectoryConnector
      tags:
        - Directory
      summary: Update a directory or outbound connector
      description: >-
        Replaces the definition (not the credential; use PUT .../credential); kind and organization are fixed. state
        disabled stops runs and deliveries at once and fails directory sign-in of the connector's accounts closed
        (upstream_unavailable). Requires If-Match. Organization scope: only the organization's own connectors are
        visible (others return 404). Changes require an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchRequired'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectoryConnectorUpdate'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryConnector'
        '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/UnprocessableEntity'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteOrgDirectoryConnector
      tags:
        - Directory
      summary: Delete a disabled connector
      description: >-
        Deletes a connector that was disabled first (409 otherwise), with its links, runs and deliveries. Accounts stay;
        their owners recover sign-in through the realm's recovery methods. Organization scope: only the organization's
        own connectors are visible (others return 404). Changes require an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: Deleted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/directory-connectors/{id}/credential:
    put:
      operationId: setOrgDirectoryConnectorCredential
      tags:
        - Directory
      summary: Replace the connector credential
      description: >-
        Replaces the encrypted bind password or bearer token; the previous one is never used again. The credential is
        write-only. Organization scope: only the organization's own connectors are visible (others return 404). Changes
        require an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                credential:
                  type: string
                  minLength: 1
                  maxLength: 4096
                  x-secret: true
              required:
                - credential
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryConnector'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/directory-connectors/{id}/test:
    post:
      operationId: testOrgDirectoryConnector
      tags:
        - Directory
      summary: Test a connector
      description: >-
        Connects, negotiates TLS and binds as the service account (ldap), or reads the downstream ServiceProviderConfig
        (scim_outbound). Changes nothing; recorded as an operator action (PROV-018). Organization scope: only the
        organization's own connectors are visible (others return 404). Changes require an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryTestResult'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/directory-connectors/{id}/runs:
    get:
      operationId: listOrgDirectoryRuns
      tags:
        - Directory
      summary: List synchronization and reconciliation runs
      description: >-
        Newest first (PROV-012, PROV-017). Organization scope: only the organization's own connectors are visible
        (others return 404).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/DirectoryRun'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: requestOrgDirectoryRun
      tags:
        - Directory
      summary: Request a run
      description: >-
        Queues a full or incremental directory synchronization, or an outbound reconciliation, as a job; at most one run
        of a connector is queued or running (409 with run_id). dry_run computes the plan with the same logic and changes
        nothing. allow_mass_deprovision overrides the deletion threshold for one applied full run and needs a reason; it
        is audited. Organization scope: only the organization's own connectors are visible (others return 404). Changes
        require an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectoryRunRequest'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryRun'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/directory-connectors/{id}/runs/{run}:
    get:
      operationId: getOrgDirectoryRun
      tags:
        - Directory
      summary: Get a run
      description: >-
        State, counts, cursors and the endpoint used. Organization scope: only the organization's own connectors are
        visible (others return 404).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_run'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryRun'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/directory-connectors/{id}/runs/{run}/findings:
    get:
      operationId: listOrgDirectoryRunFindings
      tags:
        - Directory
      summary: List a run's findings
      description: >-
        Plan items, applied changes, conflicts, divergences and errors of a run (at most 5000 stored per run; counts
        stay complete). Page with after=next_after. Organization scope: only the organization's own connectors are
        visible (others return 404).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_run'
        - $ref: '#/components/parameters/DirectoryFindingKind'
        - $ref: '#/components/parameters/DirectoryFindingsAfter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/DirectoryFinding'
                  next_after:
                    type: string
                    description: Pass as after for the next page; empty on the last page.
                required:
                  - items
                  - next_after
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/directory-connectors/{id}/health:
    get:
      operationId: getOrgDirectoryConnectorHealth
      tags:
        - Directory
      summary: Connector operational evidence
      description: >-
        Health status, last successful run, lag, endpoint health, managed record counts, outbound backlog and the latest
        operator actions (PROV-018). Never contains credentials. Organization scope: only the organization's own
        connectors are visible (others return 404).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryHealth'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/directory-connectors/{id}/deliveries:
    get:
      operationId: listOrgOutboundDeliveries
      tags:
        - Directory
      summary: List outbound deliveries
      description: >-
        Outbound provisioning deliveries (scim_outbound connectors), newest first; no payloads or credentials.
        Organization scope: only the organization's own connectors are visible (others return 404).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/OutboundDeliveryState'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/OutboundDelivery'
                  next_cursor:
                    type: string
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/directory-connectors/{id}/deliveries/{delivery}/replay:
    post:
      operationId: replayOrgOutboundDelivery
      tags:
        - Directory
      summary: Replay a dead-lettered delivery
      description: >-
        Re-opens a dead-lettered delivery as a fresh attempt series (409 for other states); recorded as an operator
        action. Organization scope: only the organization's own connectors are visible (others return 404). Changes
        require an MFA session.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: user-self-service-or-administrative
      x-permissions:
        - org.integrations.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_outbound_delivery'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/attribute-authority:
    get:
      operationId: getMyAttributeAuthority
      tags:
        - Self-service
      summary: Declare own attribute authority
      description: >-
        Which attributes and operations of the caller's account are locally editable (local), externally managed by a
        directory (externally_managed, refused with 409 conflict naming the attributes in externally_managed) or written
        back to the directory (write_back) (USR-022, PROV-013).
      security:
        - accountToken: []
      x-trust-class: user-self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeAuthority'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/users/{user}/attribute-authority:
    get:
      operationId: getUserAttributeAuthority
      tags:
        - Users
      summary: Declare a user's attribute authority
      description: >-
        Which attributes and operations of the account are locally editable, externally managed or written back
        (USR-022).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_user'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeAuthority'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/webauthn/trusted-authenticators:
    get:
      operationId: listTrustedAuthenticators
      tags:
        - Passkeys
      summary: List trusted authenticator models
      description: >-
        PASS-009. Realm-trusted authenticator models; with the operator FIDO metadata they are the trusted metadata for
        webauthn.require_trusted_attestation.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TrustedAuthenticator'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: addTrustedAuthenticator
      tags:
        - Passkeys
      summary: Trust an authenticator model
      description: >-
        PASS-009. Registrations claiming this AAGUID must carry a packed/TPM/Android attestation whose certificate
        chains to one of the roots. At most 200 per realm; 409 for a duplicate AAGUID.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - aaguid
                - description
                - root_certificates
              properties:
                aaguid:
                  type: string
                  description: Lower-case, non-zero AAGUID.
                description:
                  type: string
                  maxLength: 200
                root_certificates:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    description: One PEM CA certificate (unexpired).
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustedAuthenticator'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/webauthn/trusted-authenticators/{id}:
    delete:
      operationId: removeTrustedAuthenticator
      tags:
        - Passkeys
      summary: Stop trusting an authenticator model
      description: PASS-009. Enrolled passkeys keep working; new registrations need other trusted metadata.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /.well-known/webauthn:
    get:
      operationId: webauthnRelatedOrigins
      tags:
        - Passkeys
      summary: WebAuthn related origins document
      description: >-
        PASS-010, WebAuthn Level 3 §5.11. Served for the request host when it is the explicit rp_id of realms that
        declared webauthn.related_origins and the operator set webauthn.related_origins; 404 otherwise. Lists the
        realms' origins and related origins (at most five registrable domains).
      security: []
      x-trust-class: public-metadata
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - origins
                properties:
                  origins:
                    type: array
                    items:
                      type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/federation-transfers:
    get:
      operationId: listFederationTransfers
      tags:
        - Federation
      summary: List federation transfers
      description: FED-016.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/FederationTransfer'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createFederationTransfer
      tags:
        - Federation
      summary: Plan a federation transfer
      description: >-
        FED-016. Moves account links from one provider connection to another (same organization scope) by a migration
        map: map takes explicit entries (more can be added to the draft, up to 50000); same_subject maps every source
        link to the same subject at the target. The plan is analysed at once (summary by outcome). Accounts are never
        relinked by email.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - source_provider_id
                - target_provider_id
                - mode
                - reason
              properties:
                source_provider_id:
                  type: string
                target_provider_id:
                  type: string
                mode:
                  type: string
                  enum:
                    - map
                    - same_subject
                target_tenant:
                  type: string
                reason:
                  type: string
                  maxLength: 500
                entries:
                  type: array
                  maxItems: 2000
                  items:
                    type: object
                    additionalProperties: false
                    required:
                      - source_subject
                      - target_subject
                    properties:
                      source_subject:
                        type: string
                        maxLength: 255
                      source_issuer:
                        type: string
                        description: Needed when the subject is linked under several source issuers (multi-tenant source).
                      target_subject:
                        type: string
                        maxLength: 255
                      target_tenant:
                        type: string
                        description: Tenant substituted into a multi-tenant target issuer.
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FederationTransfer'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/federation-transfers/{id}:
    get:
      operationId: getFederationTransfer
      tags:
        - Federation
      summary: Get a federation transfer
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FederationTransfer'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/federation-transfers/{id}/entries:
    get:
      operationId: listFederationTransferEntries
      tags:
        - Federation
      summary: List transfer entries and their outcomes
      description: FED-016. Query outcome filters by outcome; after (the last seq seen) and limit page through entries.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/FederationTransferEntry'
                  next_after:
                    type: integer
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: addFederationTransferEntries
      tags:
        - Federation
      summary: Add map entries to a draft
      description: FED-016. Only for draft map transfers; the plan is analysed again.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - entries
              properties:
                entries:
                  type: array
                  minItems: 1
                  maxItems: 2000
                  items:
                    type: object
                    additionalProperties: false
                    required:
                      - source_subject
                      - target_subject
                    properties:
                      source_subject:
                        type: string
                        maxLength: 255
                      source_issuer:
                        type: string
                        description: Needed when the subject is linked under several source issuers (multi-tenant source).
                      target_subject:
                        type: string
                        maxLength: 255
                      target_tenant:
                        type: string
                        description: Tenant substituted into a multi-tenant target issuer.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FederationTransfer'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/federation-transfers/{id}/approve:
    post:
      operationId: approveFederationTransfer
      tags:
        - Federation
      summary: Approve a federation transfer
      description: >-
        FED-016. By an administrator other than the author (403 otherwise). The plan is analysed again; 409 when nothing
        could be applied.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FederationTransfer'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/federation-transfers/{id}/apply:
    post:
      operationId: applyFederationTransfer
      tags:
        - Federation
      summary: Apply an approved federation transfer
      description: >-
        FED-016. Analyses again under lock and moves only entries still ready (the link keeps its ID and account; tokens
        kept for the old connection are discarded); entries already linked at the target drop their source link.
        Collisions and duplicates are skipped and stay in the report. Applies once.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FederationTransfer'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/federation-transfers/{id}/cancel:
    post:
      operationId: cancelFederationTransfer
      tags:
        - Federation
      summary: Cancel a federation transfer
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.identity_providers.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/migration-adapters:
    get:
      operationId: listMigrationAdapters
      tags:
        - Imports and exports
      summary: List the first-party migration adapters
      description: >-
        The source products this release converts (MIG-002, MIG-018): Keycloak, ZITADEL and SuperTokens, each with the
        source versions it accepts and was tested with, how to produce the export and what converts, converts with loss
        or is unsupported. An export of another version is refused; compatibility is never inferred from the product
        name.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.import
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/MigrationAdapter'
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/migration-plans:
    post:
      operationId: planMigration
      tags:
        - Imports and exports
      summary: Convert a source export and report what would carry over (read-only)
      description: >-
        Converts a Keycloak, ZITADEL or SuperTokens export in memory (MIG-018) and returns its capability report: per
        entity type the items converted, converted with loss (and what was lost), unsupported (credential algorithms or
        parameters outside the accepted bounds, passkeys, client secrets, flows and policies, roles without a reviewed
        translation) and ignored, plus the mapping review and a mapping template. target checks the conversion against
        the realm without writing (MIG-003): which target organizations exist (by the external ID an earlier run set, or
        by the slug the mapping names), conflict (an existing organization only sharing the proposed slug, MIG-004) or
        will be created; which mapped organization roles exist; which source IDs are already imported or were deleted
        (MIG-017); and which records meet an email or username of another account. The response names records by source
        ID only and never returns credentials, seeds or contact data; the exports are not stored. Nothing is imported:
        identity-cli migrate-from --apply submits the documents through POST /organizations and POST /user-imports. The
        request is bounded by limits.max_body_bytes (256 KiB by default): plan larger exports with identity-cli
        migrate-from --plan.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.users.import
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  type: string
                  enum:
                    - keycloak
                    - zitadel
                    - supertokens
                source_version:
                  type: string
                  description: >-
                    The source product's version. Required when the export does not state it (ZITADEL; the SuperTokens
                    core API list); when the export states one, this must be that version or a leading part of it such
                    as its major version (26 for 26.8.0), otherwise 422. A version outside the adapter's supported range
                    is refused with 422.
                source_system:
                  type: string
                  pattern: ^[a-z0-9][a-z0-9._-]{0,62}$
                  description: Name qualifying every source ID (import_mappings); default <source>-<realm or app>.
                exports:
                  type: array
                  minItems: 1
                  maxItems: 20
                  items:
                    type: object
                    additionalProperties: true
                  description: >-
                    The export documents as produced by the source (a Keycloak directory export has a realm file and
                    users files).
                mapping:
                  $ref: '#/components/schemas/MigrationMapping'
                keep_attributes:
                  type: boolean
                  description: Keep source attributes and metadata as administrator-only metadata.
                import_totp:
                  type: boolean
                  description: Carry compatible TOTP seeds over (the import itself needs import_totp and its authority).
              required:
                - source
                - exports
              additionalProperties: false
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  report:
                    $ref: '#/components/schemas/MigrationReport'
                  target:
                    type: object
                    properties:
                      users:
                        type: integer
                        description: Records the conversion produced.
                      organizations:
                        type: array
                        items:
                          type: object
                          properties:
                            source_key:
                              type: string
                            slug:
                              type: string
                            display_name:
                              type: string
                            external_id:
                              type: string
                            from_mapping:
                              type: boolean
                            members:
                              type: integer
                            status:
                              type: string
                              enum:
                                - exists
                                - will_create
                                - conflict
                            id:
                              type: string
                          required:
                            - slug
                            - status
                      roles:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            exists:
                              type: boolean
                            privileged:
                              type: boolean
                            owner:
                              type: boolean
                          required:
                            - name
                            - exists
                      already_imported:
                        type: array
                        items:
                          type: string
                        description: Source IDs already imported from this source system.
                      skipped_deleted:
                        type: array
                        items:
                          type: string
                        description: Source IDs whose account was deleted here; they are never recreated (MIG-017).
                      identifier_conflicts:
                        type: array
                        items:
                          type: string
                        description: Source IDs whose email or username belongs to another account (imports never merge, MIG-004).
                    required:
                      - users
                      - organizations
                      - roles
                      - already_imported
                      - skipped_deleted
                      - identifier_conflicts
                  mapping_template:
                    $ref: '#/components/schemas/MigrationMapping'
                required:
                  - report
                  - target
                  - mapping_template
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organization-relationships:
    get:
      operationId: listAllOrganizationRelationships
      tags:
        - Organizations
      summary: List every organization relationship
      description: TEN-021. A relationship grants no access by itself.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.organizations.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrganizationRelationship'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/organization-relationships:
    get:
      operationId: listOrganizationRelationships
      tags:
        - Organizations
      summary: List an organization's relationships
      description: TEN-021. Both directions. A relationship grants no access by itself.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.relationships.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrganizationRelationship'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: proposeOrganizationRelationship
      tags:
        - Organizations
      summary: Propose an organization relationship
      description: >-
        TEN-021. From an organization administrator it is proposed until the other organization accepts; from a realm
        administrator (realm.organizations.write) it is active at once. 409 for a duplicate, a second parent or a cycle;
        hierarchies are at most 10 levels. A relationship grants no access by itself.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.relationships.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - kind
                - target_organization_id
              properties:
                kind:
                  type: string
                  enum:
                    - parent_child
                    - partner
                  description: For parent_child the path organization is the parent.
                target_organization_id:
                  type: string
                note:
                  type: string
                  maxLength: 500
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationRelationship'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/organization-relationships/{id}/accept:
    post:
      operationId: acceptOrganizationRelationship
      tags:
        - Organizations
      summary: Accept a relationship proposal
      description: TEN-021. Only the proposed-to organization decides (403 for the proposer).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.relationships.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationRelationship'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/organization-relationships/{id}/decline:
    post:
      operationId: declineOrganizationRelationship
      tags:
        - Organizations
      summary: Decline a relationship proposal
      description: TEN-021.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.relationships.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationRelationship'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/organization-relationships/{id}/end:
    post:
      operationId: endOrganizationRelationship
      tags:
        - Organizations
      summary: End a relationship
      description: >-
        TEN-021. Either side. Existing project grants stay until their owners revoke them; new tenant grants need an
        active relationship.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.relationships.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/projects/{project}/grants:
    get:
      operationId: listOwnedProjectGrants
      tags:
        - Organizations
      summary: List grants of an organization's project
      description: TEN-020. The path organization must own the project (404 otherwise).
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.projects.share
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_project'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectGrant'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: shareOwnedProject
      tags:
        - Organizations
      summary: Grant project roles to a related organization
      description: >-
        TEN-020. The grantee must have an active relationship with the owner organization (422 otherwise) unless the
        caller holds realm.projects.write. allowed_role_ids are roles of this project; the grantee can assign only
        those.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.projects.share
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_project'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - organization_id
                - allowed_role_ids
              properties:
                organization_id:
                  type: string
                allowed_role_ids:
                  type: array
                  maxItems: 50
                  items:
                    type: string
                valid_until:
                  type: string
                  format: date-time
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectGrant'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/projects/{project}/grants/{id}/revoke:
    post:
      operationId: revokeOwnedProjectGrant
      tags:
        - Organizations
      summary: Revoke a project grant
      description: TEN-020. Project roles assigned through the grant are removed in the same transaction.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.projects.share
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_project'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/project-grants:
    get:
      operationId: listReceivedProjectGrants
      tags:
        - Organizations
      summary: List project grants the organization holds
      description: TEN-020. Live grants only.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectGrant'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/project-role-assignments:
    get:
      operationId: listPartnerProjectRoleAssignments
      tags:
        - Organizations
      summary: List project roles the organization assigned
      description: TEN-020.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.roles.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectRoleAssignment'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: assignPartnerProjectRole
      tags:
        - Organizations
      summary: Assign a project role to a member
      description: >-
        TEN-020. The user must be an active member of the organization. For a project the organization does not own, the
        role must be in its active project grant (403 grant_ceiling otherwise). The assignment ends with the grant or
        the membership.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.roles.assign
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - project_id
                - role_id
                - user_id
              properties:
                project_id:
                  type: string
                role_id:
                  type: string
                user_id:
                  type: string
                expires_at:
                  type: string
                  format: date-time
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectRoleAssignment'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/organizations/{org}/project-role-assignments/{id}:
    delete:
      operationId: removePartnerProjectRole
      tags:
        - Organizations
      summary: Remove a project role the organization assigned
      description: TEN-020.
      security:
        - accountToken: []
        - adminToken: []
      x-trust-class: tenant
      x-permissions:
        - org.roles.assign
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_org'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows:
    get:
      operationId: listWorkflows
      tags:
        - Extensions
      summary: List lifecycle workflows
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createWorkflow
      tags:
        - Extensions
      summary: Create a lifecycle workflow (draft revision 1)
      description: >-
        Stores a strictly validated definition (api/workflows/definition.v1.json) as draft revision 1. Every referenced
        role, group, approver, organization and webhook subscription must exist in the realm. requires_approval is
        forced on when the realm policy extensions.workflow_publish_approval is set (EXT-015).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowCreate'
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  workflow:
                    $ref: '#/components/schemas/Workflow'
                  revision:
                    $ref: '#/components/schemas/WorkflowRevision'
                required:
                  - workflow
                  - revision
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}:
    get:
      operationId: getWorkflow
      tags:
        - Extensions
      summary: Get a lifecycle workflow
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteWorkflow
      tags:
        - Extensions
      summary: Delete a workflow that never ran
      description: >-
        A workflow with runs is kept as evidence (409; disable it instead). Plugin-managed workflows change with their
        plugin (409).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}/diagnostics:
    get:
      operationId: getWorkflowDiagnostics
      tags:
        - Extensions
      summary: Workflow health and step failures
      description: Counts, failure categories and latency over recent runs (EXT-017); never inputs, results or subjects.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowDiagnostics'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}/revisions:
    get:
      operationId: listWorkflowRevisions
      tags:
        - Extensions
      summary: List revisions, newest first
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkflowRevision'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createWorkflowRevision
      tags:
        - Extensions
      summary: Stage a new draft revision
      description: Revisions are immutable. Runs already started keep the revision they started with.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - definition
              properties:
                definition:
                  $ref: '#/components/schemas/WorkflowDefinition'
                note:
                  type: string
                  maxLength: 500
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRevision'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}/revisions/{revision}:
    get:
      operationId: getWorkflowRevision
      tags:
        - Extensions
      summary: Get a revision
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_workflow_revision'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRevision'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}/revisions/{revision}/approve:
    post:
      operationId: approveWorkflowRevision
      tags:
        - Extensions
      summary: Approve a draft revision
      description: The revision's author cannot approve it (403, AZ-018).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.publish
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_workflow_revision'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                note:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRevision'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}/revisions/{revision}/reject:
    post:
      operationId: rejectWorkflowRevision
      tags:
        - Extensions
      summary: Reject a draft revision
      description: The revision's author cannot reject it (403).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.publish
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_workflow_revision'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                note:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRevision'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}/revisions/{revision}/publish:
    post:
      operationId: publishWorkflowRevision
      tags:
        - Extensions
      summary: Publish a revision
      description: >-
        Requires recent authentication. The publisher becomes the accountable actor of every run of the revision: every
        step must be within the publisher's authority (delegation ceiling: the same checks as assigning the role or
        managing the group directly; 403 grant_ceiling_exceeded or forbidden with the offending step in errors).
        Workflows that require approval publish only approved revisions (403). A draft workflow becomes active; a
        disabled one stays disabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.publish
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_workflow_revision'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties: {}
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}/rollback:
    post:
      operationId: rollbackWorkflow
      tags:
        - Extensions
      summary: Republish an earlier revision
      description: >-
        Requires recent authentication. Publishes the content of a previously published revision as a new revision
        (history stays immutable); its approval carries over. The administrator rolling back becomes the accountable
        publisher, so their authority is checked.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.publish
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - revision
              properties:
                revision:
                  type: integer
                  minimum: 1
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}/enable:
    post:
      operationId: enableWorkflow
      tags:
        - Extensions
      summary: Enable a workflow
      description: Triggers fire again and paused runs resume. Requires a published revision (409).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.publish
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  maxLength: 64
                  description: Reason code recorded in the audit event.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}/disable:
    post:
      operationId: disableWorkflow
      tags:
        - Extensions
      summary: Disable a workflow
      description: >-
        Emergency control (SEC-020, audited as category emergency): nothing fires and runs in flight pause; compensation
        and cancellation still proceed.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.publish
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  maxLength: 64
                  description: Reason code recorded in the audit event.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflows/{id}/runs:
    get:
      operationId: listWorkflowRuns
      tags:
        - Extensions
      summary: List a workflow's runs, newest first
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - name: state
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
              - running
              - waiting
              - awaiting_approval
              - compensating
              - succeeded
              - failed
              - compensated
              - compensation_failed
              - cancelled
          description: Only runs in this state.
        - name: subject_id
          in: query
          required: false
          schema:
            type: string
          description: Only runs about this user.
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkflowRun'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: startWorkflowRun
      tags:
        - Extensions
      summary: Start a run by hand
      description: >-
        Only for workflows with a manual trigger (409 otherwise). The run executes under the publisher's authority, and
        the starter's own authority must also cover every step (403); nobody starts a run about themselves (403).
        Idempotency-Key makes a retried request return the same run.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.run
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowRunStart'
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflow-runs:
    get:
      operationId: listAllWorkflowRuns
      tags:
        - Extensions
      summary: List runs across workflows
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: state
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
              - running
              - waiting
              - awaiting_approval
              - compensating
              - succeeded
              - failed
              - compensated
              - compensation_failed
              - cancelled
          description: Only runs in this state.
        - name: subject_id
          in: query
          required: false
          schema:
            type: string
          description: Only runs about this user.
        - name: workflow_id
          in: query
          required: false
          schema:
            type: string
          description: Only runs of this workflow.
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkflowRun'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflow-runs/{id}:
    get:
      operationId: getWorkflowRun
      tags:
        - Extensions
      summary: Get a run with its step attempts and approvals
      description: >-
        Each attempt records its input version, result, retry policy, idempotency key and compensation strategy and
        state (EXT-016).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/workflow-runs/{id}/cancel:
    post:
      operationId: cancelWorkflowRun
      tags:
        - Extensions
      summary: Cancel a run
      description: >-
        The worker compensates what the run did (like a failure) and ends it cancelled. 409 when the run already
        finished or is being cancelled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.workflows.run
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties: {}
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/workflow-approvals:
    get:
      operationId: listMyWorkflowApprovals
      tags:
        - Self-service
      summary: List workflow approvals I am named on
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: state
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
              - approved
              - rejected
              - expired
              - cancelled
          description: Defaults to pending.
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkflowApproval'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/me/workflow-approvals/{id}/decision:
    post:
      operationId: decideWorkflowApproval
      tags:
        - Self-service
      summary: Approve or reject a workflow step
      description: >-
        Only a named approver decides (404 for anyone else), never the run's subject (also 404, the approval is
        concealed from them), once (409) and before the expiry (409). The run resumes on the next worker pass.
      security:
        - accountToken: []
      x-trust-class: self-service
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - decision
              properties:
                decision:
                  type: string
                  enum:
                    - approve
                    - reject
                comment:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowApproval'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/plugins:
    get:
      operationId: listPlugins
      tags:
        - Extensions
      summary: List plugins
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Plugin'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: uploadPlugin
      tags:
        - Extensions
      summary: Upload a signed plugin version
      description: >-
        Requires recent authentication. The package (api/plugins/package.v1.json) must be signed with Ed25519 by a
        publisher key in the operator's extensions.plugin_publishers (403 otherwise; there is no unsigned mode), the
        payload must match the signed digest (403), the manifest must declare every permission its parts need and only
        known ones (422), the server must support a version of every contract it requires (422 with incompatible: true),
        and every part is validated exactly like the corresponding API (422 with the part's location in errors). The
        uploader must hold every declared permission (403 grant_ceiling_exceeded). The version waits for review unless
        the realm policy extensions.plugin_review is single_admin. A plugin name belongs to its first publisher (409).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PluginPackage'
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  plugin:
                    $ref: '#/components/schemas/Plugin'
                  version:
                    $ref: '#/components/schemas/PluginVersion'
                required:
                  - plugin
                  - version
        '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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/plugins/{id}:
    get:
      operationId: getPlugin
      tags:
        - Extensions
      summary: Get a plugin with its parts
      description: '{id} is the plugin ID or name.'
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: uninstallPlugin
      tags:
        - Extensions
      summary: Uninstall a plugin
      description: >-
        Requires recent authentication. Removes every hook and webhook subscription the plugin manages; workflows that
        ran stay, disabled, as evidence. Stored versions remain. 409 while an enabled plugin depends on it.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/plugins/{id}/versions:
    get:
      operationId: listPluginVersions
      tags:
        - Extensions
      summary: List a plugin's versions
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PluginVersion'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page (API-004).
                required:
                  - items
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/plugins/{id}/versions/{version}:
    get:
      operationId: getPluginVersion
      tags:
        - Extensions
      summary: Get a version with its payload (for review)
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_plugin_version'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginVersion'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/plugins/{id}/versions/{version}/approve:
    post:
      operationId: approvePluginVersion
      tags:
        - Extensions
      summary: Approve a version
      description: >-
        Requires recent authentication. A second administrator: the uploader cannot approve (403), and the reviewer must
        hold every declared permission (403 grant_ceiling_exceeded).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.approve
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_plugin_version'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                note:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginVersion'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/plugins/{id}/versions/{version}/reject:
    post:
      operationId: rejectPluginVersion
      tags:
        - Extensions
      summary: Reject a version
      description: The uploader cannot reject their own version (403).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.approve
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_plugin_version'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                note:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginVersion'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/plugins/{id}/versions/{version}/install:
    post:
      operationId: installPluginVersion
      tags:
        - Extensions
      summary: Install, upgrade to or downgrade to a version
      description: >-
        Requires recent authentication. The version must be approved (403 while awaiting review) or previously
        installed. Signature, publisher key validity, contract compatibility, part validation and the installer's
        permissions are checked again; dependencies must be installed, enabled and recent enough (409 with
        missing_dependency). Parts are reconciled by name in one transaction: existing parts keep their IDs and signing
        secrets, new parts' secrets are returned once in signing_secrets, parts the version drops are removed. The
        previous version is kept for rollback.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/Path_plugin_version'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties: {}
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginInstallResult'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/plugins/{id}/rollback:
    post:
      operationId: rollbackPlugin
      tags:
        - Extensions
      summary: Reinstall the previous version
      description: >-
        Requires recent authentication. Reinstalls previous_version without a new review (it was reviewed and installed
        before); trust and compatibility are re-checked.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties: {}
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginInstallResult'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/plugins/{id}/enable:
    post:
      operationId: enablePlugin
      tags:
        - Extensions
      summary: Enable every part of a plugin
      description: All parts become active in one transaction. 409 when a dependency is missing or disabled.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  maxLength: 64
                  description: Reason code recorded in the audit event.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/plugins/{id}/disable:
    post:
      operationId: disablePlugin
      tags:
        - Extensions
      summary: Disable every part of a plugin
      description: >-
        Emergency control (SEC-020, audited as category emergency): every hook, webhook subscription and workflow the
        plugin manages is disabled in one transaction. 409 while an enabled plugin depends on it.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.plugins.manage
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  maxLength: 64
                  description: Reason code recorded in the audit event.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/extension-contracts:
    get:
      operationId: listExtensionContracts
      tags:
        - Extensions
      summary: Extension contract versions this server supports
      description: >-
        Webhook event schemas, the hook contract, plugin manifests, workflow definitions and the administration API are
        versioned independently (EXT-018). Any of realm.plugins.read, realm.webhooks.read, realm.hooks.read or
        realm.workflows.read suffices.
      security:
        - adminToken: []
      x-trust-class: administrative
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExtensionContract'
                  support_window_months:
                    type: integer
                required:
                  - items
                  - support_window_months
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/registry-services:
    get:
      operationId: listRegistryServices
      tags:
        - Registry
      summary: List registry services
      description: ADV-010.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RegistryService'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createRegistryService
      tags:
        - Registry
      summary: Configure a registry service
      description: >-
        ADV-010. service is the registry service name (token audience); audience names the API resource whose personal
        access tokens and API keys authenticate to it (scopes pull, push, delete cap the actions). Rules are ordered;
        the first whose repository pattern matches decides.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistryServiceInput'
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryService'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/registry-services/{id}:
    get:
      operationId: getRegistryService
      tags:
        - Registry
      summary: Get a registry service
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryService'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateRegistryService
      tags:
        - Registry
      summary: Replace a registry service
      description: ADV-010. The service name cannot change.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistryServiceInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryService'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteRegistryService
      tags:
        - Registry
      summary: Delete a registry service
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.resources.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/registry/token:
    get:
      operationId: registryToken
      tags:
        - Registry
      summary: Container-registry token (Distribution token authentication)
      description: >-
        ADV-010. Credentials are HTTP Basic: the password is a personal access token or API key minted for the registry
        service's API resource, or a machine client's secret with the client ID as user name (its service principal and
        resource grant decide). Without credentials the caller is anonymous and gets only anonymous pulls. The token
        (aud = service, short-lived, signed with the realm's signing keys published at jwks_uri) lists only granted
        actions; denied actions are left out. 401 (WWW-Authenticate: Basic) for invalid credentials; 400 for an unknown
        or disabled service. Errors use the Distribution error format.
      security: []
      x-trust-class: public-protocol-initiation
      x-optional-security:
        - registryBasic
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
        - name: service
          in: query
          required: true
          schema:
            type: string
          description: Registry service name.
        - name: scope
          in: query
          required: false
          schema:
            type: string
          description: repository:<name>:<actions>, repeatable.
        - name: account
          in: query
          required: false
          schema:
            type: string
          description: Ignored.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - token
                  - access_token
                  - expires_in
                  - issued_at
                properties:
                  token:
                    type: string
                    x-secret: true
                  access_token:
                    type: string
                    x-secret: true
                  expires_in:
                    type: integer
                  issued_at:
                    type: string
                    format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/investigations/entitlements:
    post:
      operationId: reconstructEntitlements
      tags:
        - Audit
      summary: Reconstruct historical entitlements
      description: >-
        ADV-011. Rebuilds what the subject was entitled to at the instant from retained evidence: account state,
        memberships, groups, role assignments (direct and through groups) with role definitions as they stood, the
        resulting permissions, live OAuth grants, the ABAC policy versions and realm policy revision in force.
        completeness lists caveats: application-owned facts and hook/engine decisions are never reproduced; instants
        before the retained evidence, built-in roles and roles older than the evidence are marked. The request is
        audited (investigation.entitlements.reconstructed).
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.audit.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - subject_type
                - subject_id
                - at
                - reason
              properties:
                subject_type:
                  type: string
                  enum:
                    - user
                    - service_principal
                subject_id:
                  type: string
                at:
                  type: string
                  format: date-time
                  description: A past instant.
                reason:
                  type: string
                  maxLength: 500
                  description: Investigation reference, recorded in the audit log.
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementHistory'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/ssf-transmitters:
    get:
      operationId: listSSFTransmitters
      tags:
        - Shared signals
      summary: List registered transmitters
      description: ADV-007.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SSFTransmitter'
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: registerSSFTransmitter
      tags:
        - Shared signals
      summary: Register a trusted transmitter
      description: >-
        ADV-007. Registers a source of security events: its issuer, keys (jwks_uri fetched under the delivery egress
        policy, or static public jwks), subject mapping (iss_sub through provider_id; email only with
        allow_email_subjects, verified addresses only) and an explicit action per event type. Unlisted event types are
        recorded only. The response carries the push endpoint (also the expected aud) and a push secret, shown once.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSFTransmitterInput'
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - transmitter
                  - push_secret
                properties:
                  transmitter:
                    $ref: '#/components/schemas/SSFTransmitter'
                  push_secret:
                    type: string
                    x-secret: true
                    description: Returned once; the transmitter sends it as a Bearer token with every push.
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/ssf-transmitters/{id}:
    get:
      operationId: getSSFTransmitter
      tags:
        - Shared signals
      summary: Get a transmitter
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFTransmitter'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateSSFTransmitter
      tags:
        - Shared signals
      summary: Replace a transmitter
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/IfMatchOptional'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: 'Strict JSON (application/json): duplicate members, unknown members and excess depth are rejected.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSFTransmitterInput'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFTransmitter'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteSSFTransmitter
      tags:
        - Shared signals
      summary: Delete a transmitter
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/ssf-transmitters/{id}/rotate-secret:
    post:
      operationId: rotateSSFTransmitterSecret
      tags:
        - Shared signals
      summary: Rotate the push secret
      description: ADV-007. The previous secret stops working at once.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.write
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - transmitter
                  - push_secret
                properties:
                  transmitter:
                    $ref: '#/components/schemas/SSFTransmitter'
                  push_secret:
                    type: string
                    x-secret: true
                    description: Returned once; the transmitter sends it as a Bearer token with every push.
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/realms/{realm}/ssf-transmitters/{id}/events:
    get:
      operationId: listSSFReceivedEvents
      tags:
        - Shared signals
      summary: List received events
      description: ADV-007. Minimal records (no token, no subject identifiers), kept 30 days.
      security:
        - adminToken: []
      x-trust-class: administrative
      x-permissions:
        - realm.settings.read
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        jti:
                          type: string
                        event_type:
                          type: string
                        subject_format:
                          type: string
                        user_id:
                          type: string
                        action:
                          type: string
                        outcome:
                          type: string
                        received_at:
                          type: string
                          format: date-time
                  next_cursor:
                    type: string
        '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/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /realms/{realm}/ssf/receivers/{id}/events:
    post:
      operationId: pushSecurityEvent
      tags:
        - Shared signals
      summary: Receive a pushed Security Event Token (RFC 8935)
      description: >-
        ADV-007. For a registered transmitter: Authorization: Bearer <push secret>; body is one signed SET
        (application/secevent+jwt). Checked: secret, signature against the transmitter's keys, iss, aud (this endpoint),
        jti and an iat within max_event_age_seconds (5 minutes of future skew). A replayed jti is accepted without
        effect. Each event applies the transmitter's configured action for its type (record_only otherwise); unknown
        subjects are recorded without action and answered alike. Protected accounts are never suspended (their sessions
        end instead). 202 on acceptance; 400/401 with {err, description}: invalid_request, invalid_key, invalid_issuer,
        invalid_audience, authentication_failed.
      security: []
      x-trust-class: public-protocol-initiation
      parameters:
        - $ref: '#/components/parameters/Path_realm'
        - $ref: '#/components/parameters/Path_id'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/secevent+jwt:
            schema:
              type: string
              maxLength: 65536
      responses:
        '202':
          description: Accepted
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '400':
          description: Rejected token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFPushError'
        '401':
          description: Push credentials not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSFPushError'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  securitySchemes:
    initialAccessToken:
      type: http
      scheme: bearer
      description: >-
        Initial access token (pa_iat_...) issued by an administrator for dynamic client registration (ADV-003). It
        bounds the scopes registered clients receive, counts uses and expires.
    registrationAccessToken:
      type: http
      scheme: bearer
      description: >-
        Registration access token (pa_rat_...) returned at registration (RFC 7592). It manages that one client and
        nothing else; every update returns a new one.
    scimConnectorToken:
      type: http
      scheme: bearer
      description: >-
        Provisioning connector token (pa_scim_...) issued when an organization administrator creates or rotates an
        inbound SCIM connector. It acts only within that connector organization, resource types and role ceiling.
    accountToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        User access token whose audience is the realm's account resource and which carries the proudauth:account scope,
        sent only in the Authorization header (tokens in query strings are rejected). The session, user and client must
        be live (strict-online). Refresh tokens, authorization codes, exchange tokens and support (impersonation) tokens
        are rejected.
    adminToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token whose audience is the realm's admin resource and which carries the proudauth:admin scope. User
        tokens must come from an MFA session that is not recovery-restricted; service-principal (client_credentials)
        tokens are accepted where the operation allows. Support tokens are rejected (impersonation_restricted).
    transactionToken:
      type: apiKey
      in: header
      name: X-Transaction-Token
      description: Continuation token returned when a headless transaction is started (continuation_token).
    transactionCookie:
      type: apiKey
      in: cookie
      name: pa_tx
      description: >-
        HttpOnly transaction cookie set by the authorization endpoint for browser login surfaces. State-changing steps
        also require csrfHeader and an allowed Origin.
    csrfHeader:
      type: apiKey
      in: header
      name: X-CSRF-Token
      description: >-
        CSRF token from GET .../auth/transactions/{id} (csrf_token), required with transactionCookie on state-changing
        steps.
    sessionCookie:
      type: apiKey
      in: cookie
      name: pa_sid
      description: Browser SSO session cookie (path /realms/{realm}/).
    clientSecretBasic:
      type: http
      scheme: basic
      description: >-
        OAuth client authentication with client_secret_basic. client_secret_post (client_id and client_secret form
        parameters) and private_key_jwt (client_assertion_type and client_assertion form parameters) are sent in the
        form body, which OpenAPI security schemes cannot model.
    userAccessToken:
      type: http
      scheme: bearer
      description: Access token intended for UserInfo.
    registryBasic:
      type: http
      scheme: basic
      description: >-
        Container-registry login (ADV-010): a personal access token or API key minted for the registry's resource as the
        password, or a machine client's client_id and client_secret.
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: >-
        Actor/realm/route-bound idempotency key (API-005) for POST requests, at most 255 characters (422 otherwise),
        kept for 24 hours; only a digest of the key is stored. The request is identified by its method, exact path and
        body: a replay with the same path and body returns the stored status and response with Idempotent-Replayed:
        true; the same key with a different body or another path on the same route (another resource) returns 422
        idempotency_key_reused; a request still in progress returns 409. Only successful responses are recorded: when
        the original request failed (an error or a status of 400 or above) the key is released and a retry runs again.
        Responses containing one-time secrets (members such as client_secret, token, api_key, access_token,
        refresh_token, id_token, recovery_codes, secret or webhook_secrets) are never stored or replayed (409 with
        original_status).
    IfMatchOptional:
      name: If-Match
      in: header
      required: false
      schema:
        type: string
        examples:
          - W/"v12"
      description: Expected resource version from the ETag (W/"v12" or "v12"). Stale versions return 412.
    IfMatchRequired:
      name: If-Match
      in: header
      required: true
      schema:
        type: string
        examples:
          - W/"v12"
      description: 'Expected resource version from the ETag. Required: missing returns 428, stale returns 412.'
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
      description: Opaque cursor from a previous page (next_cursor). Cursors are HMAC-bound to the realm and listing.
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
      description: Page size; defaults to limits.default_page_size and is capped at limits.max_page_size.
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      schema:
        type: string
        maxLength: 64
        pattern: ^[\x21-\x7e]+$
      description: >-
        Optional caller-supplied correlation ID (printable ASCII, at most 64 characters); otherwise generated. Echoed in
        X-Request-Id and problem request_id.
    Path_policy:
      name: policy
      in: path
      required: true
      schema:
        type: string
      description: Policy ID or name.
    Path_version:
      name: version
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
      description: Policy revision number.
    Path_source:
      name: source
      in: path
      required: true
      schema:
        type: string
        pattern: ^[a-z0-9][a-z0-9._-]{0,62}$
      description: Source system name.
    QueryHistory:
      name: history
      in: query
      required: false
      schema:
        type: boolean
      description: Include revoked consents.
    QueryTemplateName:
      name: name
      in: query
      required: false
      schema:
        type: string
      description: Only this template's versions.
    Path_alias:
      name: alias
      in: path
      required: true
      schema:
        type: string
    ScimFilter:
      name: filter
      in: query
      required: false
      schema:
        type: string
      description: RFC 7644 filter expression.
    ScimStartIndex:
      name: startIndex
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
    ScimCount:
      name: count
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 200
    ScimAttributes:
      name: attributes
      in: query
      required: false
      schema:
        type: string
      description: Comma-separated attributes to return.
    ScimExcludedAttributes:
      name: excludedAttributes
      in: query
      required: false
      schema:
        type: string
      description: Comma-separated attributes to omit.
    ScimIfMatch:
      name: If-Match
      in: header
      required: false
      schema:
        type: string
      description: ETag from a previous response; a stale value fails with 412.
    Path_name:
      name: name
      in: path
      required: true
      schema:
        type: string
      description: Resource type name.
    Path_item:
      name: item
      in: path
      required: true
      schema:
        type: string
    Path_revision:
      name: revision
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
      description: Authentication-flow revision number.
    Query_stream_id:
      name: stream_id
      in: query
      required: false
      schema:
        type: string
      description: Shared-signals stream identifier.
    Path_run:
      name: run
      in: path
      required: true
      schema:
        type: string
      description: Synchronization or reconciliation run identifier.
    Path_outbound_delivery:
      name: delivery
      in: path
      required: true
      schema:
        type: string
      description: Outbound provisioning delivery identifier.
    DirectoryFindingKind:
      name: kind
      in: query
      required: false
      schema:
        type: string
      description: >-
        Only findings of this kind (create, update, link, suspend, reactivate, deprovision, conflict, divergence, skip,
        error, group, missing_remote, drift, orphan_remote, unmanaged_remote).
    DirectoryFindingsAfter:
      name: after
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
      description: Return findings after this sequence number (next_after).
    OutboundDeliveryState:
      name: state
      in: query
      required: false
      schema:
        type: string
        enum:
          - pending
          - retrying
          - delivered
          - dead_letter
          - replayed
    Path_workflow_revision:
      name: revision
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
      description: Workflow revision number.
    Path_plugin_version:
      name: version
      in: path
      required: true
      schema:
        type: string
        pattern: ^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$
      description: Plugin version (MAJOR.MINOR.PATCH).
    Path_realm:
      name: realm
      in: path
      required: true
      schema:
        type: string
      description: Realm name (path-based issuer). Unknown realms return 404.
    Path_id:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Resource identifier.
    Path_org:
      name: org
      in: path
      required: true
      schema:
        type: string
      description: Organization identifier (a selector; access is checked, API-003).
    Path_membership:
      name: membership
      in: path
      required: true
      schema:
        type: string
      description: Membership identifier.
    Path_assignment:
      name: assignment
      in: path
      required: true
      schema:
        type: string
      description: Role assignment identifier.
    Path_role:
      name: role
      in: path
      required: true
      schema:
        type: string
      description: Role identifier.
    Path_group:
      name: group
      in: path
      required: true
      schema:
        type: string
      description: Group identifier.
    Path_member:
      name: member
      in: path
      required: true
      schema:
        type: string
      description: Membership identifier of the group member.
    Path_user:
      name: user
      in: path
      required: true
      schema:
        type: string
      description: User identifier.
    Path_project:
      name: project
      in: path
      required: true
      schema:
        type: string
      description: Project identifier.
    Path_client:
      name: client
      in: path
      required: true
      schema:
        type: string
      description: Client reference (internal client id, not the OAuth client_id).
    Path_resource:
      name: resource
      in: path
      required: true
      schema:
        type: string
      description: Resource (API) identifier.
    Path_scope:
      name: scope
      in: path
      required: true
      schema:
        type: string
      description: Scope identifier.
    Path_subject:
      name: subject
      in: path
      required: true
      schema:
        type: string
      description: Subject identifier (svc_ prefix denotes a service principal).
    Path_delivery:
      name: delivery
      in: path
      required: true
      schema:
        type: string
      description: Webhook delivery identifier.
    Path_connection:
      name: connection
      in: path
      required: true
      schema:
        type: string
      description: Federation connection (identity provider) alias.
  headers:
    X-Request-Id:
      description: Correlation identifier for this request.
      schema:
        type: string
    ETag:
      description: Weak resource version, W/"v{version}". Send it back in If-Match.
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    Idempotent-Replayed:
      description: Present (true) when the response was replayed from the idempotency store.
      schema:
        type: string
        enum:
          - 'true'
    Location:
      description: Redirect target.
      schema:
        type: string
        format: uri
    WWW-Authenticate:
      description: Authentication challenge.
      schema:
        type: string
    Set-Cookie:
      description: >-
        HttpOnly, Secure (outside insecure development mode) cookie: pa_tx (path /api/v1/realms/{realm}/auth/) or pa_sid
        (path /realms/{realm}/).
      schema:
        type: string
  responses:
    ScimError:
      description: SCIM error (RFC 7644 section 3.12).
      content:
        application/scim+json:
          schema:
            $ref: '#/components/schemas/ScimErrorDocument'
    BadRequest:
      description: >-
        Malformed request, invalid JSON (duplicate members, unknown fields, wrong types), invalid cursor or invalid
        transaction (code invalid_request, transaction_invalid, invalid_proof, invitation_invalid).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: Missing or invalid credentials (code unauthenticated or invalid_credentials). Includes WWW-Authenticate.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        WWW-Authenticate:
          $ref: '#/components/headers/WWW-Authenticate'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: >-
        Authenticated but not allowed (code forbidden, mfa_required, step_up_required, recent_authentication_required,
        grant_ceiling_exceeded, impersonation_restricted, account_unavailable, sso_required, recovery_restricted).
        Step-up problems carry obligations.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: Unknown realm or resource, or existence concealed from the caller (code not_found, feature_disabled).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: >-
        Conflicts with current state, or an idempotent request with the same key is still in progress / carried a
        one-time secret (code conflict, unexpected_step, last_owner, last_sign_in_method).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Gone:
      description: The authentication transaction expired (code transaction_expired).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    PreconditionFailed:
      description: If-Match does not match the current version (code precondition_failed).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    PayloadTooLarge:
      description: Body exceeds limits.max_body_bytes (code payload_too_large).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    UnsupportedMediaType:
      description: Wrong Content-Type (code unsupported_media_type).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    UnprocessableEntity:
      description: >-
        Validation failed (code validation_failed, password_policy, idempotency_key_reused); errors maps fields to
        messages.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    PreconditionRequired:
      description: If-Match header is required (code precondition_required).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    TooManyRequests:
      description: Rate limited (code rate_limited). Includes Retry-After; never discloses per-user state.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    InternalError:
      description: Unexpected error (code internal_error); no stack traces or secrets.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ServiceUnavailable:
      description: >-
        Load shedding, realm unavailable or dependency failure (code unavailable, upstream_unavailable). May include
        Retry-After.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NoContent:
      description: Success; no content.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
    OAuthError:
      description: >-
        OAuth 2.0 error (RFC 6749). invalid_client responses use 401 with WWW-Authenticate; throttled requests include
        Retry-After.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        WWW-Authenticate:
          $ref: '#/components/headers/WWW-Authenticate'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
  schemas:
    AdminUser:
      type: object
      description: Administrative user view.
      properties:
        id:
          type: string
        state:
          type: string
          enum:
            - pending_verification
            - active
            - suspended
            - locked
            - recovery_restricted
            - pending_deletion
            - deleted
        display_name:
          type: string
        given_name:
          type: string
        family_name:
          type: string
        locale:
          type: string
        zoneinfo:
          type: string
        profile:
          type:
            - object
            - 'null'
          additionalProperties: true
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/UserIdentifier'
        required_actions:
          type:
            - array
            - 'null'
          items:
            type: string
            enum:
              - update_password
              - verify_email
              - configure_totp
              - accept_terms
              - complete_profile
              - verify_contact
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        version:
          type: integer
          format: int64
        deletion_scheduled_at:
          type:
            - string
            - 'null'
          format: date-time
        admin_metadata:
          type:
            - object
            - 'null'
          additionalProperties: true
        protected:
          type: boolean
        authz_revision:
          type: integer
          format: int64
        last_login_at:
          type:
            - string
            - 'null'
          format: date-time
        created_via:
          type: string
        locked_until:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - state
        - display_name
        - given_name
        - family_name
        - locale
        - zoneinfo
        - profile
        - identifiers
        - required_actions
        - created_at
        - updated_at
        - version
        - deletion_scheduled_at
        - admin_metadata
        - protected
        - authz_revision
        - last_login_at
        - created_via
        - locked_until
    AdminUserPatch:
      additionalProperties: false
      properties:
        admin_metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
        display_name:
          type:
            - string
            - 'null'
        family_name:
          type:
            - string
            - 'null'
        given_name:
          type:
            - string
            - 'null'
        locale:
          type:
            - string
            - 'null'
        profile:
          additionalProperties: {}
          type:
            - object
            - 'null'
        zoneinfo:
          type:
            - string
            - 'null'
      type: object
    ApplicationImpersonationPolicy:
      additionalProperties: false
      properties:
        allowed_scopes:
          items:
            type: string
          type:
            - array
            - 'null'
        contract_validated_at:
          type: string
        contract_version:
          type: string
        support_client_ids:
          items:
            type: string
          type:
            - array
            - 'null'
        write_scopes:
          items:
            type: string
          type:
            - array
            - 'null'
        write_actions:
          description: >-
            Reviewed state-changing actions an allowlisted_write support token may perform through the decision API
            (IMP-011).
          items:
            type: string
          type:
            - array
            - 'null'
      type: object
    ApplicationScope:
      additionalProperties: false
      properties:
        consent_text:
          type: string
        description:
          type: string
        id:
          type: string
        is_default:
          type: boolean
          description: >-
            Granted by default (APP-007) when a request names the scope's resource but none of its scopes, subject to
            the checks of a requested scope; see ScopeInput.is_default. Has no effect on protocol (oidc) scopes.
        kind:
          type: string
        name:
          type: string
        resource_id:
          type: string
        sensitivity:
          type: string
      required:
        - id
        - is_default
        - kind
        - name
        - sensitivity
      type: object
    ApplicationTokenPolicy:
      additionalProperties: false
      properties:
        access_token_ttl_seconds:
          type: integer
        refresh_absolute_seconds:
          type: integer
        refresh_idle_seconds:
          type: integer
        require_dpop:
          type: boolean
        require_mfa:
          type: boolean
        require_par:
          type: boolean
        max_session_age_seconds:
          type: integer
          minimum: 0
          maximum: 7776000
          description: Re-authenticate users whose SSO session is older than this (SES-002).
      type: object
    AuditEvent:
      additionalProperties: false
      properties:
        actor:
          $ref: '#/components/schemas/AuditRef'
        batch_id:
          type: string
        category:
          type: string
        client_id:
          type: string
        content_hash:
          type: string
        grant_id:
          type: string
        id:
          type: string
        impersonation_grant_id:
          type: string
        ip_context:
          type: string
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
        occurred_at:
          format: date-time
          type: string
        org_id:
          type: string
        outcome:
          type: string
        realm_id:
          type: string
        reason_code:
          type: string
        reporting_service:
          type: string
        request_id:
          type: string
        schema_version:
          type: integer
        session_id:
          type: string
        source:
          type: string
        subject:
          oneOf:
            - $ref: '#/components/schemas/AuditRef'
            - type: 'null'
        target:
          oneOf:
            - $ref: '#/components/schemas/AuditRef'
            - type: 'null'
        type:
          type: string
      required:
        - actor
        - id
        - occurred_at
        - outcome
        - schema_version
        - source
        - type
      type: object
    AuditRef:
      additionalProperties: false
      properties:
        id:
          type: string
        session_id:
          type: string
        type:
          type: string
      required:
        - id
        - type
      type: object
    AuditVerificationReport:
      additionalProperties: false
      properties:
        batches_checked:
          type: integer
        events_checked:
          type: integer
        ok:
          type: boolean
        problems:
          items:
            type: string
          type:
            - array
            - 'null'
        unsealed_events:
          type: integer
      required:
        - batches_checked
        - events_checked
        - ok
        - problems
        - unsealed_events
      type: object
    AuthzScope:
      additionalProperties: false
      properties:
        id:
          type: string
        type:
          type: string
          description: realm, organization or project.
      type: object
    AuthzSubject:
      additionalProperties: false
      properties:
        id:
          type: string
        type:
          type: string
          description: user, group or service_principal.
      type: object
    ClaimFieldMapping:
      additionalProperties: false
      properties:
        claim:
          type: string
        mode:
          type: string
          enum:
            - on_create
            - sync
          description: on_create (default) fills the field only at account creation; sync refreshes it on every upstream login.
      type: object
    ClaimMapping:
      additionalProperties: false
      properties:
        display_name:
          $ref: '#/components/schemas/ClaimFieldMapping'
        family_name:
          $ref: '#/components/schemas/ClaimFieldMapping'
        given_name:
          $ref: '#/components/schemas/ClaimFieldMapping'
        locale:
          $ref: '#/components/schemas/ClaimFieldMapping'
        zoneinfo:
          $ref: '#/components/schemas/ClaimFieldMapping'
      type: object
    Client:
      additionalProperties: false
      properties:
        access_token_claims:
          additionalProperties: {}
          type:
            - object
            - 'null'
        allow_offline_access:
          type: boolean
        allow_remember_me:
          type: boolean
        allowed_origins:
          items:
            type: string
          type:
            - array
            - 'null'
        backchannel_logout_uri:
          type: string
        frontchannel_logout_uri:
          type: string
          description: >-
            Front-channel logout (SES-018): loaded in an iframe when a session the client took part in ends at the
            logout endpoint. Same scheme, host and port as a registered redirect URI. Browser privacy controls may keep
            it from working; back-channel logout is the reliable mechanism.
        frontchannel_logout_session_required:
          type: boolean
          description: Add iss and sid to frontchannel_logout_uri. Requires frontchannel_logout_uri.
        id_token_encrypted_response_alg:
          type: string
          enum:
            - RSA-OAEP-256
            - ECDH-ES
            - ECDH-ES+A128KW
            - ECDH-ES+A256KW
          description: >-
            TOK-020: encrypt ID tokens (signed, then encrypted: a nested JWT) to the client's newest active registered
            public key that fits (use enc or no use; RSA for RSA-OAEP-256, EC for ECDH-ES). Issuance fails with
            unauthorized_client when no key fits.
        id_token_encrypted_response_enc:
          type: string
          enum:
            - A128GCM
            - A256GCM
          description: Required with id_token_encrypted_response_alg (the specification default A128CBC-HS256 is not offered).
        userinfo_signed_response_alg:
          type: string
          enum:
            - RS256
            - PS256
            - ES256
            - EdDSA
          description: 'OIDC-013: return UserInfo as a JWT signed with the realm key; must be the realm''s signing algorithm.'
        userinfo_encrypted_response_alg:
          type: string
          enum:
            - RSA-OAEP-256
            - ECDH-ES
            - ECDH-ES+A128KW
            - ECDH-ES+A256KW
        userinfo_encrypted_response_enc:
          type: string
          enum:
            - A128GCM
            - A256GCM
        authorization_signed_response_alg:
          type: string
          enum:
            - RS256
            - PS256
            - ES256
            - EdDSA
          description: >-
            JARM (ADV-002): the signing algorithm of JWT authorization responses; must be the realm's (responses are
            always signed with the realm key).
        authorization_encrypted_response_alg:
          type: string
          enum:
            - RSA-OAEP-256
            - ECDH-ES
            - ECDH-ES+A128KW
            - ECDH-ES+A256KW
          description: 'JARM: encrypt JWT authorization responses (nested, signed first) to the client''s registered key.'
        authorization_encrypted_response_enc:
          type: string
          enum:
            - A128GCM
            - A256GCM
        tls_client_auth_subject_dn:
          type: string
          description: >-
            tls_client_auth (RFC 8705): the certificate must chain to a realm client trust anchor and carry exactly one
            registered identity: this subject DN (RFC 4514 as Go prints it) or one SAN below.
        tls_client_auth_san_dns:
          type: string
        tls_client_auth_san_uri:
          type: string
        tls_client_auth_san_ip:
          type: string
        tls_client_auth_san_email:
          type: string
        tls_client_certificate_bound_access_tokens:
          type: boolean
          description: >-
            TOK-019: every access token is bound to the presented TLS client certificate (cnf x5t#S256); a token request
            without a certificate is refused (invalid_request), never answered with a bearer token.
        client_id:
          type: string
        client_type:
          type: string
          enum:
            - confidential
            - public_browser
            - native
            - device
            - machine
        consent_mode:
          type: string
        consent_terms_version:
          type: string
        contacts:
          items:
            type: string
          type:
            - array
            - 'null'
        created_at:
          format: date-time
          type: string
        default_resource_id:
          type: string
        description:
          type: string
        dynamically_registered:
          type: boolean
        environment:
          type: string
        first_party:
          type: boolean
        grant_types:
          items:
            type: string
          type:
            - array
            - 'null'
        id:
          type: string
        id_token_claims:
          additionalProperties: {}
          type:
            - object
            - 'null'
        login_ui_url:
          type: string
        name:
          type: string
        owner_user_id:
          type: string
        post_logout_redirect_uris:
          items:
            type: string
          type:
            - array
            - 'null'
        project_id:
          type: string
        realm_id:
          type: string
        redirect_uris:
          items:
            type: string
          type:
            - array
            - 'null'
        sector_identifier:
          type: string
        protocol:
          type: string
          enum:
            - oidc
            - saml
          description: >-
            saml for the client backing a SAML application; managed only through /saml/applications (PUT
            /clients/{client} answers 409) and refused by every OAuth endpoint.
        security_profile:
          type: string
        service_principal_id:
          type: string
        state:
          type: string
          enum:
            - active
            - suspended
            - decommissioned
        subject_type:
          type: string
        token_endpoint_auth_method:
          type: string
        token_policy:
          $ref: '#/components/schemas/ApplicationTokenPolicy'
        updated_at:
          format: date-time
          type: string
        version:
          format: int64
          type: integer
      required:
        - allow_offline_access
        - allow_remember_me
        - allowed_origins
        - client_id
        - client_type
        - consent_mode
        - created_at
        - dynamically_registered
        - environment
        - first_party
        - grant_types
        - id
        - name
        - post_logout_redirect_uris
        - realm_id
        - redirect_uris
        - security_profile
        - state
        - subject_type
        - token_endpoint_auth_method
        - token_policy
        - updated_at
        - version
      type: object
    ClientCredential:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        display_prefix:
          type: string
        expires_at:
          format: date-time
          type:
            - string
            - 'null'
        id:
          type: string
        key_id:
          type: string
        kind:
          type: string
        last_used_at:
          format: date-time
          type:
            - string
            - 'null'
        state:
          type: string
      required:
        - created_at
        - id
        - kind
        - state
      type: object
    ClientInput:
      additionalProperties: false
      properties:
        access_token_claims:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: >-
            Static values, or attribute mappings {"$attr": "user.<given_name|family_name|display_name|locale|zoneinfo>"
            or "profile.<claimable attribute>", "transform": "lower|upper", "default": "..."} (APP-011). At most 20
            claims; reserved claims are refused; profile attributes not marked claimable are never released.
        allow_offline_access:
          type: boolean
        allow_remember_me:
          type: boolean
        allowed_origins:
          items:
            type: string
          type:
            - array
            - 'null'
        backchannel_logout_uri:
          type: string
        frontchannel_logout_uri:
          type: string
          description: >-
            Front-channel logout (SES-018): loaded in an iframe when a session the client took part in ends at the
            logout endpoint. Same scheme, host and port as a registered redirect URI. Browser privacy controls may keep
            it from working; back-channel logout is the reliable mechanism.
        frontchannel_logout_session_required:
          type: boolean
          description: Add iss and sid to frontchannel_logout_uri. Requires frontchannel_logout_uri.
        id_token_encrypted_response_alg:
          type: string
          enum:
            - RSA-OAEP-256
            - ECDH-ES
            - ECDH-ES+A128KW
            - ECDH-ES+A256KW
          description: >-
            TOK-020: encrypt ID tokens (signed, then encrypted: a nested JWT) to the client's newest active registered
            public key that fits (use enc or no use; RSA for RSA-OAEP-256, EC for ECDH-ES). Issuance fails with
            unauthorized_client when no key fits.
        id_token_encrypted_response_enc:
          type: string
          enum:
            - A128GCM
            - A256GCM
          description: Required with id_token_encrypted_response_alg (the specification default A128CBC-HS256 is not offered).
        userinfo_signed_response_alg:
          type: string
          enum:
            - RS256
            - PS256
            - ES256
            - EdDSA
          description: 'OIDC-013: return UserInfo as a JWT signed with the realm key; must be the realm''s signing algorithm.'
        userinfo_encrypted_response_alg:
          type: string
          enum:
            - RSA-OAEP-256
            - ECDH-ES
            - ECDH-ES+A128KW
            - ECDH-ES+A256KW
        userinfo_encrypted_response_enc:
          type: string
          enum:
            - A128GCM
            - A256GCM
        authorization_signed_response_alg:
          type: string
          enum:
            - RS256
            - PS256
            - ES256
            - EdDSA
          description: >-
            JARM (ADV-002): the signing algorithm of JWT authorization responses; must be the realm's (responses are
            always signed with the realm key).
        authorization_encrypted_response_alg:
          type: string
          enum:
            - RSA-OAEP-256
            - ECDH-ES
            - ECDH-ES+A128KW
            - ECDH-ES+A256KW
          description: 'JARM: encrypt JWT authorization responses (nested, signed first) to the client''s registered key.'
        authorization_encrypted_response_enc:
          type: string
          enum:
            - A128GCM
            - A256GCM
        tls_client_auth_subject_dn:
          type: string
          description: >-
            tls_client_auth (RFC 8705): the certificate must chain to a realm client trust anchor and carry exactly one
            registered identity: this subject DN (RFC 4514 as Go prints it) or one SAN below.
        tls_client_auth_san_dns:
          type: string
        tls_client_auth_san_uri:
          type: string
        tls_client_auth_san_ip:
          type: string
        tls_client_auth_san_email:
          type: string
        tls_client_certificate_bound_access_tokens:
          type: boolean
          description: >-
            TOK-019: every access token is bound to the presented TLS client certificate (cnf x5t#S256); a token request
            without a certificate is refused (invalid_request), never answered with a bearer token.
        client_id:
          type: string
          maxLength: 128
          description: Generated when omitted; at most 128 URL-safe characters.
        client_type:
          type: string
          enum:
            - confidential
            - public_browser
            - native
            - device
            - machine
        consent_mode:
          type: string
          description: Defaults to preauthorized for first-party clients and required otherwise.
        consent_terms_version:
          type: string
          maxLength: 64
          description: >-
            The client's current terms (APP-013). Consents record the version they were given for; a consent for another
            version no longer covers the client, so users are asked again.
        contacts:
          items:
            type: string
          type:
            - array
            - 'null'
        default_resource_id:
          type: string
        description:
          type: string
        environment:
          type: string
          description: >-
            Defaults to production (or the project's environment); controls redirect URI and origin registration rules.
            Fixed at registration (APP-015): register a new client instead of changing it. Clients of a project must use
            the project's environment, and token exchange never accepts a token minted for a client of another
            environment.
        first_party:
          type: boolean
        grant_types:
          items:
            type: string
          type:
            - array
            - 'null'
          description: Allowed per client type; password and implicit grants are unsupported. Defaults depend on client_type.
        id_token_claims:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: >-
            Static values, or attribute mappings {"$attr": "user.<given_name|family_name|display_name|locale|zoneinfo>"
            or "profile.<claimable attribute>", "transform": "lower|upper", "default": "..."} (APP-011). At most 20
            claims; reserved claims are refused and standard user claims are released by scope, never mapped; profile
            attributes not marked claimable are never released.
        jwks:
          description: Public JWK Set for private_key_jwt client authentication.
        login_ui_url:
          type: string
        name:
          type: string
          maxLength: 200
        owner_user_id:
          type: string
        post_logout_redirect_uris:
          items:
            type: string
          type:
            - array
            - 'null'
        project_id:
          type: string
        redirect_uris:
          items:
            type: string
          type:
            - array
            - 'null'
        sector_identifier:
          type: string
        security_profile:
          type: string
          enum:
            - standard
            - third_party
            - privileged
            - high_assurance
            - fapi2
          description: >-
            Defaults to standard. fapi2 (ADV-001) enforces the FAPI 2.0 Security Profile: confidential client,
            private_key_jwt (PS256, ES256 or EdDSA) or mutual TLS, authorization code (and refresh tokens) only, PAR
            required, sender-constrained tokens (require_dpop or tls_client_certificate_bound_access_tokens), https
            redirects, a realm signing algorithm of PS256/ES256/EdDSA, 60-second codes, access tokens of at most 10
            minutes, refresh tokens not rotated. Not certified by the OpenID Foundation.
        service_principal_id:
          type: string
        subject_type:
          type: string
          enum:
            - public
            - pairwise
          description: Defaults to public; pairwise requires sector_identifier.
        token_endpoint_auth_method:
          type: string
          enum:
            - client_secret_basic
            - client_secret_post
            - private_key_jwt
            - none
            - tls_client_auth
            - self_signed_tls_client_auth
          description: >-
            Defaults to client_secret_basic for confidential and machine clients and none for public, native and device
            clients. tls_client_auth and self_signed_tls_client_auth (RFC 8705, MCH-014; confidential and machine
            clients) authenticate with the TLS client certificate presented on the mutual-TLS endpoint (or through a
            trusted proxy).
        token_policy:
          $ref: '#/components/schemas/ApplicationTokenPolicy'
      type: object
      required:
        - client_type
        - name
    ConfigDocument:
      type: object
      description: Configuration-as-code document (also published as api/schemas/config-document.schema.json).
      additionalProperties: false
      properties:
        client_resource_grants:
          additionalProperties:
            additionalProperties:
              items:
                type: string
              type:
                - array
                - 'null'
            type:
              - object
              - 'null'
          type:
            - object
            - 'null'
          description: client_id -> resource audience -> allowed scopes.
        clients:
          items:
            $ref: '#/components/schemas/ClientInput'
          type:
            - array
            - 'null'
        format:
          type: string
        permissions:
          items:
            $ref: '#/components/schemas/Permission'
          type:
            - array
            - 'null'
        policy:
          oneOf:
            - $ref: '#/components/schemas/RealmPolicy'
            - type: 'null'
        resources:
          items:
            $ref: '#/components/schemas/ResourceInput'
          type:
            - array
            - 'null'
        roles:
          items:
            $ref: '#/components/schemas/RoleInput'
          type:
            - array
            - 'null'
    ConfigPlan:
      additionalProperties: false
      properties:
        drift:
          items:
            type: string
          type: array
          description: >-
            Existing objects that differ from the document, with the differing members (SDK-012), for example "client
            web-bff: redirect_uris differ". An import never rewrites existing objects: reconcile them through the API.
        create:
          items:
            type: string
          type:
            - array
            - 'null'
        errors:
          items:
            type: string
          type:
            - array
            - 'null'
        notes:
          items:
            type: string
          type:
            - array
            - 'null'
        unchanged:
          items:
            type: string
          type:
            - array
            - 'null'
        update:
          items:
            type: string
          type:
            - array
            - 'null'
      required:
        - create
        - errors
        - notes
        - unchanged
        - update
      type: object
    Consent:
      type: object
      properties:
        id:
          type: string
        client_id:
          type: string
        client_name:
          type: string
        scopes:
          type:
            - array
            - 'null'
          items:
            type: string
        granted_at:
          type: string
          format: date-time
        client:
          type: string
          description: Client reference (cli_...).
        resource_ids:
          type: array
          items:
            type: string
        terms_version:
          type: string
        mode:
          type: string
          enum:
            - user
            - preauthorized
          description: >-
            user: given by the user on the consent screen; preauthorized: covered by an administrative
            pre-authorization.
        preauthorization_id:
          type: string
        revoked_at:
          type: string
          format: date-time
      required:
        - id
        - client_id
        - client_name
        - scopes
        - granted_at
    CredentialInventoryItem:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        display_prefix:
          type: string
        expires_at:
          format: date-time
          type: string
        flags:
          items:
            type: string
          type:
            - array
            - 'null'
        id:
          type: string
        kind:
          type: string
        last_used_at:
          format: date-time
          type:
            - string
            - 'null'
        name:
          type: string
        organization_id:
          type: string
        owner_id:
          type: string
        owner_type:
          type: string
        resource_id:
          type: string
        revoked_at:
          format: date-time
          type:
            - string
            - 'null'
        scopes:
          items:
            type: string
          type:
            - array
            - 'null'
        state:
          type: string
      required:
        - created_at
        - display_prefix
        - expires_at
        - flags
        - id
        - kind
        - name
        - owner_id
        - owner_type
        - resource_id
        - scopes
        - state
      type: object
    CustomerSupportGrant:
      type: object
      properties:
        id:
          type: string
        organization_id:
          type: string
        mode:
          type: string
        state:
          type: string
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        revoked_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - organization_id
        - mode
        - state
        - expires_at
        - created_at
        - revoked_at
    Policy:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        scope_type:
          type: string
          enum:
            - realm
            - organization
        scope_id:
          type: string
        state:
          type: string
          enum:
            - draft
            - active
            - disabled
        active_version:
          type: integer
        requires_approval:
          type: boolean
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    PolicyCreate:
      type: object
      properties:
        owner_user_id:
          type: string
          description: Accountable owner (DOM-009); defaults to the creating user.
        name:
          type: string
          maxLength: 100
        description:
          type: string
        scope_type:
          type: string
          enum:
            - realm
            - organization
        scope_id:
          type: string
        requires_approval:
          type: boolean
        definition:
          $ref: '#/components/schemas/PolicyDefinition'
        note:
          type: string
          maxLength: 500
      required:
        - name
        - definition
      additionalProperties: false
    PolicyVersion:
      type: object
      properties:
        id:
          type: string
        policy_id:
          type: string
        version_number:
          type: integer
        definition:
          $ref: '#/components/schemas/PolicyDefinition'
        definition_hash:
          type: string
        status:
          type: string
          enum:
            - staged
            - approved
            - published
            - superseded
            - rejected
        author_id:
          type: string
        approved_by_id:
          type: string
        note:
          type: string
        created_at:
          type: string
          format: date-time
        approved_at:
          type: string
          format: date-time
        published_at:
          type: string
          format: date-time
    PolicyDefinition:
      type: object
      description: >-
        Typed, bounded policy (≤ 50 rules, condition depth ≤ 8, ≤ 64 nodes, ≤ 64 KiB). Attributes: action, subject.*
        (id, type, assurance, acr, roles, is_support, actor_id, client_id, org_id, auth_age_seconds), resource.* (type,
        id, org_id), context.* (asserted by the calling service), environment.* (now_unix, hour_utc, weekday).
      properties:
        description:
          type: string
        target:
          type: object
          properties:
            actions:
              type: array
              items:
                type: string
                description: Exact action or namespace prefix ending in .*
            resource_types:
              type: array
              items:
                type: string
          required:
            - actions
          additionalProperties: false
        rules:
          type: array
          maxItems: 50
          items:
            type: object
            properties:
              id:
                type: string
              description:
                type: string
              effect:
                type: string
                enum:
                  - deny
                  - require
              actions:
                type: array
                items:
                  type: string
              when:
                $ref: '#/components/schemas/PolicyCondition'
              reason_code:
                type: string
              obligations:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - reauthenticate
                        - approval
                        - justification
                    required_profile:
                      type: string
                      enum:
                        - mfa
                        - phishing_resistant
                    max_age_seconds:
                      type: integer
                    approvals:
                      type: integer
                  required:
                    - type
                  additionalProperties: false
            required:
              - id
              - effect
            additionalProperties: false
      required:
        - target
        - rules
      additionalProperties: false
    PolicyCondition:
      type: object
      description: >-
        Exactly one of all, any, not or op. Comparisons over missing attributes are unknown, and unknown rule conditions
        apply the rule (fail closed).
      properties:
        all:
          type: array
          items:
            $ref: '#/components/schemas/PolicyCondition'
        any:
          type: array
          items:
            $ref: '#/components/schemas/PolicyCondition'
        not:
          $ref: '#/components/schemas/PolicyCondition'
        op:
          type: string
          enum:
            - eq
            - ne
            - lt
            - le
            - gt
            - ge
            - in
            - contains
            - starts_with
            - exists
        attr:
          type: string
        value: {}
        value_attr:
          type: string
      additionalProperties: false
    Decision:
      additionalProperties: false
      properties:
        allowed:
          type: boolean
        cache_ttl_seconds:
          type: integer
          description: >-
            Cache contract (AZ-019): reuse the decision for at most this many seconds, only for requests with the same
            cache_key; 0 means do not cache. Decisions that involve ABAC policies, hooks, step-up obligations, support
            access or privileged actions are never cacheable.
        cache_key:
          type: string
          description: >-
            Opaque key covering realm, subject, actor, client, organization, resource, action, the subject's
            authorization revision, the policy version and the asserted context; any role, membership or policy change
            produces a different key.
        decision_id:
          type: string
        obligations:
          items:
            additionalProperties: {}
            type:
              - object
              - 'null'
          type:
            - array
            - 'null'
        policy_version:
          type: string
        reason_code:
          type: string
      required:
        - allowed
        - cache_ttl_seconds
        - decision_id
        - obligations
        - policy_version
        - reason_code
      type: object
    DecisionRequest:
      additionalProperties: false
      properties:
        action:
          type: string
        context:
          additionalProperties: {}
          type:
            - object
            - 'null'
        resource:
          additionalProperties: false
          properties:
            id:
              type: string
            org_id:
              type: string
            project_id:
              type: string
              maxLength: 128
              description: >-
                Project the resource belongs to (AZ-002): the subject's project-scoped roles for it are evaluated too,
                and only there. It must exist in the realm and, with an organization, belong to it (owned, or shared
                through an active project grant).
            type:
              type: string
          required:
            - id
            - org_id
            - type
          type: object
        subject:
          additionalProperties: false
          properties:
            id:
              type: string
            type:
              type: string
          required:
            - id
            - type
          type:
            - object
            - 'null'
          description: Free-form subject; only evaluated for callers holding realm.authorization.simulate.
        subject_token:
          type: string
          x-secret: true
          description: The end user's access token, validated with introspection authority of the calling resource server.
      type: object
    DevMail:
      type: object
      properties:
        id:
          type: string
        recipient:
          type: string
        subject:
          type: string
        body:
          type: string
        template:
          type: string
        created_at:
          type: string
          format: date-time
    DeviceAuthorizationResponse:
      additionalProperties: false
      properties:
        device_code:
          type: string
          x-secret: true
        expires_in:
          type: integer
        interval:
          type: integer
        user_code:
          type: string
        verification_uri:
          type: string
        verification_uri_complete:
          type: string
      required:
        - device_code
        - expires_in
        - interval
        - user_code
        - verification_uri
      type: object
    Domain:
      additionalProperties: false
      properties:
        challenge_expires_at:
          format: date-time
          type:
            - string
            - 'null'
        created_at:
          format: date-time
          type: string
        domain:
          type: string
        id:
          type: string
        recheck_at:
          format: date-time
          type:
            - string
            - 'null'
        state:
          type: string
        verified_at:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - created_at
        - domain
        - id
        - state
      type: object
    DomainChallenge:
      additionalProperties: false
      properties:
        dns_record_name:
          type: string
        dns_record_type:
          type: string
        dns_record_value:
          type: string
        domain:
          $ref: '#/components/schemas/Domain'
      required:
        - dns_record_name
        - dns_record_type
        - dns_record_value
        - domain
      type: object
    EffectivePermissions:
      type: object
      properties:
        scope:
          $ref: '#/components/schemas/AuthzScope'
        roles:
          type:
            - array
            - 'null'
          items:
            type: string
        permissions:
          type:
            - array
            - 'null'
          items:
            type: string
        provenance:
          type: object
          additionalProperties:
            type:
              - array
              - 'null'
            items:
              type: string
          description: permission -> granting role names
        denied_permissions:
          type: array
          items:
            type: string
        sources:
          type: array
          description: >-
            Assignments producing the permissions (AZ-009): via realm, organization, group or project; conditional
            grants report whether they apply now. Realm-level sources are redacted for organization administrators.
          items:
            type: object
            properties:
              assignment_id:
                type: string
              role_id:
                type: string
              role_name:
                type: string
              via:
                type: string
                enum:
                  - realm
                  - organization
                  - group
                  - project
              group_id:
                type: string
              conditional:
                type: boolean
              applies:
                type: boolean
              expires_at:
                type: string
                format: date-time
              permissions:
                type: array
                items:
                  type: string
              redacted:
                type: boolean
        policies:
          type: array
          description: >-
            Published policies that may restrict decisions; named only for callers holding realm.policies.read.
            Definitions are never included.
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              version:
                type: integer
              scope:
                type: string
        restricting_policies:
          type: integer
        project_id:
          type: string
          description: >-
            The project whose project-scoped assignments were evaluated with the scope (query parameter project_id,
            AZ-002).
      required:
        - scope
        - roles
        - permissions
        - provenance
    ExchangePolicy:
      additionalProperties: false
      properties:
        accept_from_audiences:
          items:
            type: string
          type:
            - array
            - 'null'
        max_scopes:
          items:
            type: string
          type:
            - array
            - 'null'
      type: object
    Group:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        description:
          type: string
        external_id:
          type: string
        id:
          type: string
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
        name:
          type: string
        organization_id:
          type: string
        parent_id:
          type: string
        source:
          type: string
        version:
          format: int64
          type: integer
      required:
        - created_at
        - id
        - metadata
        - name
        - organization_id
        - source
        - version
      type: object
    GroupInput:
      additionalProperties: false
      properties:
        description:
          type: string
        external_id:
          type: string
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
        name:
          type: string
        parent_id:
          type:
            - string
            - 'null'
      type: object
    GroupMember:
      type: object
      properties:
        membership_id:
          type: string
        user_id:
          type: string
        source:
          type: string
        added_at:
          type: string
          format: date-time
      required:
        - membership_id
        - user_id
        - source
        - added_at
    IdentityProvider:
      additionalProperties: false
      properties:
        adapter:
          type: string
          description: The provider adapter; saml for a SAML connection (FED-014).
        alias:
          type: string
        claim_mapping:
          $ref: '#/components/schemas/ClaimMapping'
        config:
          $ref: '#/components/schemas/IdentityProviderConfig'
        created_at:
          format: date-time
          type: string
        display_name:
          type: string
        has_client_secret:
          type: boolean
        id:
          type: string
        issuer:
          type: string
        jit_default_role_id:
          type: string
        jit_provisioning:
          type: boolean
        kind:
          type: string
          description: >-
            oidc, oauth2_social or saml. SAML connections are listed here; PUT answers 409 for them (manage them under
            /saml/connections) and POST /identity-providers/{id}/test reports SAML certificate diagnostics without
            contacting the provider.
        linking_policy:
          type: string
        mapping_revision:
          format: int64
          type: integer
        organization_id:
          type: string
        state:
          type: string
        trust_upstream_mfa:
          type: boolean
        updated_at:
          format: date-time
          type: string
        version:
          format: int64
          type: integer
      required:
        - adapter
        - alias
        - claim_mapping
        - config
        - created_at
        - display_name
        - has_client_secret
        - id
        - issuer
        - jit_provisioning
        - kind
        - linking_policy
        - mapping_revision
        - state
        - trust_upstream_mfa
        - updated_at
        - version
      type: object
    IdentityProviderConfig:
      additionalProperties: false
      properties:
        algorithms:
          items:
            type: string
          type:
            - array
            - 'null'
        allowed_email_domains:
          items:
            type: string
          type:
            - array
            - 'null'
        allowed_tenants:
          items:
            type: string
          type:
            - array
            - 'null'
        api_base_url:
          type: string
        authorization_endpoint:
          type: string
        client_auth:
          type: string
          enum:
            - client_secret_basic
            - client_secret_post
          description: Defaults to client_secret_basic.
        client_id:
          type: string
        discovery_url:
          type: string
        end_session_endpoint:
          type: string
        jwks_uri:
          type: string
        multi_tenant_issuer:
          type: boolean
        scopes:
          items:
            type: string
          type:
            - array
            - 'null'
          maxItems: 20
          description: OIDC connections must request openid.
        tenant_claim:
          type: string
        token_endpoint:
          type: string
        trusted_acr_values:
          items:
            type: string
          type:
            - array
            - 'null'
      type: object
      required:
        - client_id
    IdentityProviderDiagnostics:
      additionalProperties: false
      properties:
        authorization_endpoint:
          type: string
        issuer:
          type: string
        jwks_uri:
          type: string
        ok:
          type: boolean
        problems:
          items:
            type: string
          type:
            - array
            - 'null'
        signing_keys:
          type: integer
        supports_pkce_s256:
          type: boolean
        token_endpoint:
          type: string
      required:
        - issuer
        - ok
        - problems
        - signing_keys
        - supports_pkce_s256
      type: object
    IdentityProviderInput:
      additionalProperties: false
      properties:
        adapter:
          type: string
          pattern: ^[a-z][a-z0-9_-]{0,31}$
          description: >-
            Defaults to oidc. Built-in adapters (FED-002): oidc (generic OpenID Connect), github (OAuth 2.0 with the
            REST user API; numeric account ID as subject; only verified emails), google (fixed issuer
            https://accounts.google.com; allowed_tenants restricts to Workspace domains through the hd claim), microsoft
            (Entra ID work and school accounts: issuer https://login.microsoftonline.com/{tenant}/v2.0 selected by tid,
            allowed_tenants required; its email claim is never treated as verified, so trusted_verified_email linking is
            refused). Deployments can register further adapters in code; unknown names are refused.
        alias:
          type: string
          description: Lower-case letters, digits and dashes (2..63). Part of the registered callback URL; cannot be changed.
        claim_mapping:
          oneOf:
            - $ref: '#/components/schemas/ClaimMapping'
            - type: 'null'
        client_secret:
          type:
            - string
            - 'null'
          x-secret: true
          format: password
          description: >-
            Upstream client secret (write-only; stored encrypted and never returned, see has_client_secret). On PUT,
            omit to keep the current secret; an empty string clears it.
        config:
          $ref: '#/components/schemas/IdentityProviderConfig'
        display_name:
          type: string
          maxLength: 100
        issuer:
          type: string
          description: >-
            Upstream issuer; required for OIDC connections. May contain {tenant} for multi-tenant issuers. Cannot change
            while identities are linked.
        jit_default_role_id:
          type: string
        jit_provisioning:
          type: boolean
        linking_policy:
          type: string
          enum:
            - verify_existing
            - trusted_verified_email
            - create_only
        organization_id:
          type: string
        state:
          type: string
          enum:
            - active
            - disabled
        trust_upstream_mfa:
          type: boolean
      type: object
      required:
        - alias
        - config
        - display_name
    ImpersonationGrant:
      additionalProperties: false
      properties:
        actor_user_id:
          type: string
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          type: string
        mode:
          type: string
        organization_id:
          type: string
        request_id:
          type: string
        resource_id:
          type: string
        revoke_reason:
          type: string
        revoked_at:
          format: date-time
          type:
            - string
            - 'null'
        scope_ceiling:
          items:
            type: string
          type:
            - array
            - 'null'
        state:
          type: string
        target_user_id:
          type: string
      required:
        - actor_user_id
        - created_at
        - expires_at
        - id
        - mode
        - organization_id
        - request_id
        - resource_id
        - scope_ceiling
        - state
        - target_user_id
      type: object
    ImpersonationIssued:
      additionalProperties: false
      properties:
        access_token:
          type: string
          x-secret: true
          description: Support (impersonation) access token. Returned once; never replayed.
        expires_in:
          type: integer
        grant:
          $ref: '#/components/schemas/ImpersonationGrant'
        scope:
          type: string
        token_type:
          type: string
      required:
        - access_token
        - expires_in
        - grant
        - scope
        - token_type
      type: object
    ImpersonationRequest:
      additionalProperties: false
      properties:
        actor_user_id:
          type: string
        approval_required:
          type: string
        approved_by:
          type: string
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          type: string
        mode:
          type: string
        organization_id:
          type: string
        resource_id:
          type: string
        scopes:
          items:
            type: string
          type:
            - array
            - 'null'
        state:
          type: string
        target_user_id:
          type: string
        ticket_reference:
          type: string
      required:
        - actor_user_id
        - approval_required
        - created_at
        - expires_at
        - id
        - mode
        - organization_id
        - resource_id
        - scopes
        - state
        - target_user_id
      type: object
    ImpersonationRequestInput:
      additionalProperties: false
      properties:
        audience:
          type: string
        client_id:
          type: string
        mode:
          type: string
          enum:
            - read_only
            - allowlisted_write
        organization_id:
          type: string
        reason:
          type: string
        scopes:
          items:
            type: string
          type:
            - array
            - 'null'
        target_user_id:
          type: string
        ticket_reference:
          type: string
        ttl_seconds:
          type: integer
      type: object
      required:
        - reason
        - target_user_id
    IntrospectionResponse:
      type: object
      additionalProperties: true
      description: >-
        RFC 7662 introspection response. Inactive, unknown, revoked or out-of-audience tokens return only {"active":
        false}.
      properties:
        active:
          type: boolean
        iss:
          type: string
        sub:
          type: string
        aud:
          type: string
        client_id:
          type: string
        scope:
          type: string
        exp:
          type: integer
          format: int64
        iat:
          type: integer
          format: int64
        jti:
          type: string
        token_kind:
          type: string
        token_type:
          type: string
          enum:
            - Bearer
            - DPoP
          description: >-
            DPoP for a token bound to a DPoP key (cnf.jkt, RFC 9449 section 6.2); Bearer otherwise, also for
            certificate-bound tokens (RFC 8705).
        authz_version:
          type: integer
          format: int64
        org_id:
          type: string
        sid:
          type: string
        auth_time:
          type: integer
          format: int64
        acr:
          type: string
        act:
          type: object
          additionalProperties: true
        cnf:
          type: object
          additionalProperties: true
        agent:
          type: boolean
          const: true
          description: >-
            Present (true) when the subject is a service principal registered as an autonomous agent (MCH-017): for its
            JWT and opaque access tokens and its API keys.
        subject_type:
          type: string
        impersonation_grant_id:
          type: string
      required:
        - active
    Invitation:
      additionalProperties: false
      properties:
        accepted_at:
          format: date-time
          type:
            - string
            - 'null'
        accepted_by_user_id:
          type: string
        allowed_domains:
          items:
            type: string
          type:
            - array
            - 'null'
        created_at:
          format: date-time
          type: string
        delivery_state:
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          type: string
        inviter_id:
          type: string
        inviter_type:
          type: string
        max_uses:
          type: integer
        batch_id:
          type: string
        superseded_by:
          type: string
          description: Set when an administrator reassigned this invitation (INV-014).
        membership_id:
          type: string
        organization_id:
          type: string
        project_id:
          type: string
        purpose:
          type: string
        role_ids:
          items:
            type: string
          type:
            - array
            - 'null'
        secret_version:
          type: integer
        send_count:
          type: integer
        state:
          type: string
        target_email:
          type: string
        target_user_id:
          type: string
        use_count:
          type: integer
        version:
          format: int64
          type: integer
      required:
        - created_at
        - delivery_state
        - expires_at
        - id
        - inviter_id
        - inviter_type
        - max_uses
        - organization_id
        - purpose
        - role_ids
        - secret_version
        - send_count
        - state
        - use_count
        - version
      type: object
    InvitationAcceptance:
      additionalProperties: false
      description: >-
        Organization invitations return membership_id; project invitations (INV-012) return project_id and
        assignment_ids and create no membership.
      properties:
        invitation_id:
          type: string
        membership_id:
          type: string
        organization_id:
          type: string
        project_id:
          type: string
        assignment_ids:
          type: array
          items:
            type: string
      required:
        - invitation_id
        - organization_id
      type: object
    InvitationInput:
      additionalProperties: false
      properties:
        allowed_domains:
          items:
            type: string
          type:
            - array
            - 'null'
        email:
          type: string
          description: Target email; an email or user_id is required unless purpose is shared_link.
        locale:
          type: string
        max_uses:
          type: integer
        message:
          type: string
        project_id:
          type: string
        purpose:
          type: string
          enum:
            - organization_membership
            - project_access
            - shared_link
          description: Defaults to organization_membership.
        role_ids:
          items:
            type: string
          type:
            - array
            - 'null'
          maxItems: 10
        ttl_hours:
          type: integer
        user_id:
          type: string
      type: object
    InvitationInspection:
      additionalProperties: false
      properties:
        expires_at:
          format: date-time
          type: string
        organization_id:
          type: string
        organization_name:
          type: string
        purpose:
          type: string
        requires_account:
          type: boolean
      required:
        - expires_at
        - organization_id
        - organization_name
        - purpose
        - requires_account
      type: object
    JWKSet:
      type: object
      description: Public verification keys (RFC 7517). Never contains private key material.
      properties:
        keys:
          type: array
          items:
            type: object
            additionalProperties: true
      required:
        - keys
    Job:
      additionalProperties: false
      properties:
        attempts:
          type: integer
        cancel_requested:
          type: boolean
        created_at:
          format: date-time
          type: string
        dry_run:
          type: boolean
        finished_at:
          format: date-time
          type:
            - string
            - 'null'
        has_protected_result:
          type: boolean
        id:
          type: string
        input:
          additionalProperties: {}
          type:
            - object
            - 'null'
          description: >-
            The non-secret job input as submitted. Secret-bearing input (user.import records with password verifiers,
            TOTP seeds and contact data) is stored as protected input: encrypted at rest, never returned here, and
            erased when the job finishes.
        last_error:
          type: string
        organization_id:
          type: string
        progress:
          additionalProperties: {}
          type:
            - object
            - 'null'
        realm_id:
          type: string
        requested_by_id:
          type: string
        requested_by_type:
          type: string
        result:
          additionalProperties: {}
          type:
            - object
            - 'null'
        result_expires_at:
          format: date-time
          type:
            - string
            - 'null'
        state:
          type: string
          description: queued, running, succeeded, failed or cancelled.
        type:
          type: string
      required:
        - attempts
        - cancel_requested
        - created_at
        - dry_run
        - has_protected_result
        - id
        - progress
        - requested_by_id
        - requested_by_type
        - state
        - type
      type: object
    JobAccepted:
      type: object
      description: Reference to an asynchronous job; poll GET /api/v1/realms/{realm}/jobs/{id}.
      properties:
        job_id:
          type: string
      required:
        - job_id
    JoinRequest:
      additionalProperties: false
      properties:
        reviewer_ids:
          type: array
          items:
            type: string
          description: >-
            Assigned reviewers; empty when any member holding org.join_requests.review may decide. Always empty in the
            requester's own listing.
        created_at:
          format: date-time
          type: string
        decided_at:
          format: date-time
          type:
            - string
            - 'null'
        decided_by:
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          type: string
        organization_id:
          type: string
        reason:
          type: string
        state:
          type: string
        user_id:
          type: string
      required:
        - created_at
        - expires_at
        - id
        - organization_id
        - state
        - user_id
      type: object
    LinkedIdentity:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        email_hint:
          type: string
        id:
          type: string
        last_used_at:
          format: date-time
          type:
            - string
            - 'null'
        provenance:
          type: string
        provider:
          type: string
        provider_display_name:
          type: string
        provider_id:
          type: string
      required:
        - created_at
        - id
        - provenance
        - provider
        - provider_display_name
        - provider_id
      type: object
    MachineCredential:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        display_prefix:
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          type: string
        kind:
          type: string
          enum:
            - api_key
            - personal_token
        last_used_at:
          format: date-time
          type:
            - string
            - 'null'
        name:
          type: string
        organization_id:
          type: string
        owner_id:
          type: string
        owner_type:
          type: string
        resource_id:
          type: string
        revoked_at:
          format: date-time
          type:
            - string
            - 'null'
        scopes:
          items:
            type: string
          type:
            - array
            - 'null'
        state:
          type: string
      required:
        - created_at
        - display_prefix
        - expires_at
        - id
        - kind
        - name
        - owner_id
        - owner_type
        - resource_id
        - scopes
        - state
      type: object
    MachineCredentialInput:
      additionalProperties: false
      properties:
        audience:
          type: string
        name:
          type: string
        organization_id:
          type: string
        scopes:
          items:
            type: string
          type:
            - array
            - 'null'
        ttl_days:
          type: integer
          maximum: 365
          description: Expiry is mandatory; at most 365 days.
      type: object
      required:
        - audience
        - name
        - scopes
    MaskedUser:
      type: object
      description: Masked view returned to support operators holding only support.users.read (identifier values are masked).
      properties:
        id:
          type: string
        state:
          type: string
        display_name:
          type: string
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/UserIdentifier'
        created_at:
          type: string
          format: date-time
        last_login_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - state
        - display_name
        - identifiers
        - created_at
        - last_login_at
    Membership:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        display_name:
          type: string
        email:
          type: string
        expires_at:
          format: date-time
          type:
            - string
            - 'null'
        external_id:
          type: string
        id:
          type: string
        joined_at:
          format: date-time
          type:
            - string
            - 'null'
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Organization membership metadata (USR-009), at most limits.metadata_bytes as JSON. Present only for callers
            holding org.members.write in the organization; never shown to the member or put in tokens.
        organization_id:
          type: string
        removed_at:
          format: date-time
          type:
            - string
            - 'null'
        revision:
          format: int64
          type: integer
        roles:
          items:
            type: string
          type:
            - array
            - 'null'
        source:
          type: string
        source_reference:
          type: string
        state:
          type: string
        user_id:
          type: string
      required:
        - created_at
        - id
        - organization_id
        - revision
        - source
        - state
        - user_id
      type: object
    MembershipSummary:
      type: object
      properties:
        membership_id:
          type: string
        organization_id:
          type: string
        slug:
          type: string
        display_name:
          type: string
        membership_state:
          type: string
        organization_state:
          type: string
        joined_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - membership_id
        - organization_id
        - slug
        - display_name
        - membership_state
        - organization_state
        - joined_at
    NotificationJob:
      additionalProperties: false
      properties:
        attempts:
          type: integer
        channel:
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: string
        last_error:
          type: string
        recipient_hint:
          type: string
        reference_id:
          type: string
        reference_type:
          type: string
        state:
          type: string
        template:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - attempts
        - channel
        - created_at
        - id
        - recipient_hint
        - state
        - template
        - updated_at
      type: object
    NotificationTemplate:
      type: object
      properties:
        id:
          type: string
        organization_id:
          type: string
        event_type:
          type: string
        locale:
          type: string
        subject:
          type: string
        body_text:
          type: string
        version:
          type: integer
      required:
        - id
        - organization_id
        - event_type
        - locale
        - subject
        - body_text
        - version
    OAuthError:
      type: object
      description: OAuth 2.0 error response (RFC 6749 section 5.2) used by protocol endpoints.
      properties:
        error:
          type: string
        error_description:
          type: string
      required:
        - error
    Obligation:
      type: object
      description: A mandatory condition the caller must satisfy (or deny).
      properties:
        type:
          type: string
          enum:
            - reauthenticate
        required_profile:
          type: string
        max_age_seconds:
          type: integer
      required:
        - type
    OpenIDConfiguration:
      type: object
      description: >-
        OpenID Provider / OAuth 2.0 Authorization Server metadata. Optional endpoints are advertised only when the
        capability is enabled.
      properties:
        issuer:
          type: string
          format: uri
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        jwks_uri:
          type: string
        userinfo_endpoint:
          type: string
        introspection_endpoint:
          type: string
        revocation_endpoint:
          type: string
        end_session_endpoint:
          type: string
        device_authorization_endpoint:
          type: string
        pushed_authorization_request_endpoint:
          type: string
        registration_endpoint:
          type: string
        check_session_iframe:
          type: string
          description: OpenID Connect Session Management 1.0 (OIDC-014); present only when the realm turned it on.
        response_types_supported:
          type: array
          items:
            type: string
        response_modes_supported:
          type: array
          items:
            type: string
        grant_types_supported:
          type: array
          items:
            type: string
        subject_types_supported:
          type: array
          items:
            type: string
        id_token_signing_alg_values_supported:
          type: array
          items:
            type: string
        userinfo_signing_alg_values_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_signing_alg_values_supported:
          type: array
          items:
            type: string
        introspection_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        revocation_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        code_challenge_methods_supported:
          type: array
          items:
            type: string
        scopes_supported:
          type: array
          items:
            type: string
        claims_supported:
          type: array
          items:
            type: string
        claims_parameter_supported:
          type: boolean
        request_parameter_supported:
          type: boolean
        request_uri_parameter_supported:
          type: boolean
        require_request_uri_registration:
          type: boolean
        require_pushed_authorization_requests:
          type: boolean
        prompt_values_supported:
          type: array
          items:
            type: string
        acr_values_supported:
          type: array
          items:
            type: string
        authorization_response_iss_parameter_supported:
          type: boolean
        authorization_signing_alg_values_supported:
          type: array
          items:
            type: string
          description: 'JARM (ADV-002): algorithms of the published signing keys.'
        authorization_encryption_alg_values_supported:
          type: array
          items:
            type: string
          description: 'JARM response encryption: RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A256KW.'
        authorization_encryption_enc_values_supported:
          type: array
          items:
            type: string
          description: 'JARM content encryption: A128GCM, A256GCM.'
        id_token_encryption_alg_values_supported:
          type: array
          items:
            type: string
          description: 'TOK-020: RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A256KW.'
        id_token_encryption_enc_values_supported:
          type: array
          items:
            type: string
          description: A128GCM, A256GCM.
        userinfo_encryption_alg_values_supported:
          type: array
          items:
            type: string
          description: 'OIDC-013: RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A256KW.'
        userinfo_encryption_enc_values_supported:
          type: array
          items:
            type: string
          description: A128GCM, A256GCM.
        tls_client_certificate_bound_access_tokens:
          type: boolean
          description: >-
            true when client certificates reach the server (server.mtls_listen or server.client_cert_header; RFC 8705,
            TOK-019); false otherwise.
        mtls_endpoint_aliases:
          type: object
          description: >-
            RFC 8705 §5: the mutual-TLS listener's endpoints, present only when server.mtls_origin is set.
            pushed_authorization_request_endpoint and device_authorization_endpoint appear with those capabilities.
          properties:
            token_endpoint:
              type: string
            introspection_endpoint:
              type: string
            revocation_endpoint:
              type: string
            userinfo_endpoint:
              type: string
            pushed_authorization_request_endpoint:
              type: string
            device_authorization_endpoint:
              type: string
          additionalProperties: false
        frontchannel_logout_supported:
          type: boolean
          description: 'OIDC Front-Channel Logout 1.0 (SES-018): true with the logout endpoint.'
        frontchannel_logout_session_supported:
          type: boolean
          description: >-
            true with the logout endpoint: iss and sid are added to the front-channel logout URI when the client asks
            for them.
        backchannel_logout_supported:
          type: boolean
        backchannel_logout_session_supported:
          type: boolean
        dpop_signing_alg_values_supported:
          type: array
          items:
            type: string
        service_documentation:
          type: string
      required:
        - issuer
        - authorization_endpoint
        - token_endpoint
        - jwks_uri
        - response_types_supported
        - subject_types_supported
        - id_token_signing_alg_values_supported
    OrgPolicy:
      additionalProperties: false
      properties:
        audit_retention_days:
          type: integer
          minimum: 30
          maximum: 3650
          description: >-
            Keeps this organization's audit evidence at least this many days (AUD-009); it never shortens the realm's or
            deployment's retention.
        personal_tokens:
          type: string
          enum:
            - allowed
            - disabled
          description: disabled forbids personal access tokens in this organization's context (MCH-006).
        personal_token_max_days:
          type: integer
          minimum: 0
          maximum: 365
        registration_mode:
          type: string
          enum:
            - inherit
            - public
            - closed
            - invitation_only
            - domain_restricted
          description: >-
            Narrows realm registration in this organization's context (REG-001): requested organization, invited
            organization, or the organization owning the email domain. It can only tighten the realm mode.
        allowed_scopes:
          type: array
          items:
            type: string
          description: >-
            Organization scope ceiling (TOK-008); tokens in this organization's context carry only these business
            scopes.
        allowed_email_domains:
          items:
            type: string
          type:
            - array
            - 'null'
        allowed_login_methods:
          items:
            type: string
          type:
            - array
            - 'null'
        impersonation_approval:
          type: string
        invitations_enabled:
          type:
            - boolean
            - 'null'
        join_requests_enabled:
          type: boolean
        mfa_required:
          type: boolean
        session_absolute_seconds:
          type: integer
        session_idle_seconds:
          type: integer
        sso_provider_id:
          type: string
        sso_required:
          type: boolean
        support_access_opt_out:
          type: boolean
      type: object
    Organization:
      additionalProperties: false
      properties:
        authz_revision:
          format: int64
          type: integer
        contact:
          additionalProperties: {}
          type:
            - object
            - 'null'
        created_at:
          format: date-time
          type: string
        display_name:
          type: string
        external_id:
          type: string
        id:
          type: string
        locale:
          type: string
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
        policy:
          $ref: '#/components/schemas/OrgPolicy'
        realm_id:
          type: string
        slug:
          type: string
        state:
          type: string
        time_zone:
          type: string
        updated_at:
          format: date-time
          type: string
        version:
          format: int64
          type: integer
      required:
        - authz_revision
        - contact
        - created_at
        - display_name
        - id
        - metadata
        - policy
        - realm_id
        - slug
        - state
        - updated_at
        - version
      type: object
    OrganizationDeletionPreview:
      additionalProperties: false
      properties:
        active_grants:
          type: integer
        active_members:
          type: integer
        active_support_grants:
          type: integer
        owned_projects:
          type: integer
        owned_clients:
          type: integer
          description: Active clients of the organization's projects and service principals; suspended at once.
        pending_invitations:
          type: integer
        provisioning_connectors:
          type: integer
        role_assignments:
          type: integer
          description: Role assignments scoped to the organization; removed.
        groups:
          type: integer
        verified_domains:
          type: integer
        owned_service_principals:
          type: integer
          description: Service principals owned by the organization; disabled at once.
        active_automation_credentials:
          type: integer
          description: API keys and personal tokens in the organization; revoked at once.
        webhook_subscriptions:
          type: integer
          description: Organization webhooks; disabled at once and deleted with their secrets when the deletion finishes.
        identity_providers:
          type: integer
          description: Organization identity providers; disabled at once, client secrets erased when the deletion finishes.
        mail_server_configured:
          type: boolean
          description: An organization mail server (TEN-022); its configuration and credential are erased.
        consent_preauthorizations:
          type: integer
          description: Live administrative consent pre-authorizations for the organization; revoked at once.
        export_results:
          type: integer
          description: Job results (exports) of the organization still downloadable; erased at once.
        pending_jobs:
          type: integer
          description: Queued or running jobs of the organization; cancelled at once.
        retained_audit_events:
          type: integer
          description: Audit events about the organization; retained under the audit retention policy and legal holds.
        active_legal_holds:
          type: integer
          description: >-
            Active legal holds that keep evidence of the organization: realm-wide holds, holds on the organization, and
            holds on an account that is a member of it (in any membership state).
        retained:
          type: array
          items:
            type: string
          description: What the deletion keeps.
      required:
        - active_grants
        - active_members
        - active_support_grants
        - owned_projects
        - pending_invitations
        - provisioning_connectors
      type: object
    OrganizationInput:
      additionalProperties: false
      properties:
        contact:
          additionalProperties: {}
          type:
            - object
            - 'null'
        display_name:
          type: string
          maxLength: 200
        external_id:
          type: string
        locale:
          type: string
        metadata:
          additionalProperties: {}
          type:
            - object
            - 'null'
        policy:
          oneOf:
            - $ref: '#/components/schemas/OrgPolicy'
            - type: 'null'
        slug:
          type: string
          description: 2-63 lowercase letters, digits or dashes; derived when omitted.
        time_zone:
          type: string
      type: object
      required:
        - display_name
    Passkey:
      additionalProperties: false
      properties:
        aaguid:
          type: string
        attestation_trusted:
          type: boolean
          description: 'PASS-009: the attestation chained to trusted metadata; otherwise the AAGUID is self-reported.'
        attestation_format:
          type: string
        backup_eligible:
          type: boolean
        created_at:
          format: date-time
          type: string
        discoverable:
          type: boolean
        id:
          type: string
        last_used_at:
          format: date-time
          type:
            - string
            - 'null'
        name:
          type: string
        synced:
          type: boolean
        transports:
          items:
            type: string
          type:
            - array
            - 'null'
        user_verified:
          type: boolean
      required:
        - backup_eligible
        - created_at
        - discoverable
        - id
        - name
        - synced
        - transports
        - user_verified
      type: object
    PasskeyRegistrationOptions:
      type: object
      properties:
        ceremony_id:
          type: string
        public_key:
          type: object
          additionalProperties: true
          description: W3C WebAuthn PublicKeyCredentialCreationOptions (JSON encoding) to pass to navigator.credentials.create().
        expires_at:
          type: string
          format: date-time
      required:
        - ceremony_id
        - public_key
        - expires_at
    PasswordResetRequested:
      additionalProperties: false
      properties:
        expires_at:
          format: date-time
          type: string
        message:
          type: string
        reset_id:
          type: string
      required:
        - expires_at
        - message
        - reset_id
      type: object
    Permission:
      additionalProperties: false
      properties:
        built_in:
          type: boolean
        description:
          type: string
        id:
          type: string
        name:
          type: string
        namespace:
          type: string
        owner_resource_id:
          type: string
        resource_type:
          type: string
        sensitivity:
          type: string
          description: Defaults to normal. Privileged permissions produce step-up obligations in decisions.
      type: object
      required:
        - name
    RememberedDevice:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
    AssignmentRequest:
      type: object
      properties:
        id:
          type: string
        role_id:
          type: string
        subject:
          type: object
          properties:
            type:
              type: string
            id:
              type: string
        scope:
          type: object
          properties:
            type:
              type: string
            id:
              type: string
        conditions:
          $ref: '#/components/schemas/GrantConditions'
        valid_from:
          type: string
          format: date-time
        assignment_expires_at:
          type: string
          format: date-time
        reason:
          type: string
        requested_by:
          type: string
        state:
          type: string
          enum:
            - pending
            - approved
            - rejected
            - expired
        decided_by:
          type: string
        decided_at:
          type: string
          format: date-time
        assignment_id:
          type: string
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    HookInput:
      type: object
      properties:
        owner_user_id:
          type: string
          description: Accountable owner (DOM-009); defaults to the creating user.
        name:
          type: string
        kind:
          type: string
          enum:
            - registration.eligibility
            - profile.validation
            - token.claims
            - authorization.decision
            - authentication.risk
        url:
          type: string
          format: uri
        timeout_ms:
          type: integer
          minimum: 100
          maximum: 5000
        failure_mode:
          type: string
          enum:
            - deny
            - skip
        client_ids:
          type: array
          items:
            type: string
        allow_private_network:
          type: boolean
        state:
          type: string
          enum:
            - active
            - disabled
        contract_version:
          type: integer
          enum:
            - 1
          description: Hook contract version (EXT-018), sent as ProudAuth-Hook-Version; default 1. See api/hooks.
      required:
        - name
        - kind
        - url
      additionalProperties: false
    Hook:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        kind:
          type: string
        url:
          type: string
        timeout_ms:
          type: integer
        failure_mode:
          type: string
        client_ids:
          type: array
          items:
            type: string
        allow_private_network:
          type: boolean
        state:
          type: string
        invocations:
          type: integer
        failures:
          type: integer
        last_latency_ms:
          type: integer
        last_failure_at:
          type: string
          format: date-time
        last_error:
          type: string
        contract_version:
          type: integer
          description: Hook contract version (EXT-018).
        plugin_id:
          type: string
          description: Set when a plugin manages the hook; PUT and DELETE then return 409 (EXT-014).
        version:
          type: integer
        created_at:
          type: string
          format: date-time
    ActivityEvent:
      type: object
      properties:
        type:
          type: string
        occurred_at:
          type: string
          format: date-time
        outcome:
          type: string
        network:
          type: string
          description: Privacy-reduced network context.
        client_id:
          type: string
        performed_by:
          type: string
          description: Actor type when someone other than the account owner acted.
        support_grant_id:
          type: string
        reason_code:
          type: string
        details:
          type: object
    InvitationBatchResult:
      type: object
      properties:
        index:
          type: integer
        status:
          type: integer
          description: HTTP status the entry would have produced on its own.
        invitation_id:
          type: string
        error:
          type: object
          description: Problem summary (code, title, detail, errors) for a failed entry.
      required:
        - index
        - status
    ProjectGrant:
      type: object
      properties:
        id:
          type: string
        project_id:
          type: string
        organization_id:
          type: string
        allowed_role_ids:
          type: array
          items:
            type: string
        state:
          type: string
          enum:
            - active
            - suspended
            - revoked
        valid_until:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    GrantConditions:
      type: object
      additionalProperties: false
      description: >-
        Conditions on a role assignment (AZ-012). Unknown members are rejected; a condition that cannot be evaluated for
        the trusted request context fails closed. The support capability members (IMP-002, IMP-007) apply only to
        support access and bound the organizations, target categories, modes and scopes an operator may use, re-checked
        on every use of a grant.
      properties:
        client_ids:
          type: array
          maxItems: 50
          items:
            type: string
        resources:
          type: array
          maxItems: 50
          items:
            type: string
          description: Resource IDs or audiences.
        min_assurance:
          type: string
          enum:
            - mfa
            - phishing_resistant
        max_auth_age_seconds:
          type: integer
          minimum: 0
          maximum: 86400
        active_hours_utc:
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: integer
        weekdays:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 6
        organization_ids:
          type: array
          maxItems: 200
          items:
            type: string
        subject_categories:
          type: array
          items:
            type: string
            enum:
              - member
              - guest
        support_modes:
          type: array
          items:
            type: string
            enum:
              - read_only
              - allowlisted_write
        support_scopes:
          type: array
          maxItems: 50
          items:
            type: string
    ScimResource:
      type: object
      description: A SCIM resource or discovery document.
      additionalProperties: true
      properties:
        schemas:
          type: array
          items:
            type: string
        id:
          type: string
        externalId:
          type: string
        meta:
          type: object
          additionalProperties: true
    ScimListResponse:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        totalResults:
          type: integer
        startIndex:
          type: integer
        itemsPerPage:
          type: integer
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ScimResource'
      required:
        - schemas
        - totalResults
    ScimUser:
      type: object
      additionalProperties: true
      properties:
        schemas:
          type: array
          items:
            type: string
        userName:
          type: string
        externalId:
          type: string
        displayName:
          type: string
        name:
          type: object
          properties:
            givenName:
              type: string
            familyName:
              type: string
        emails:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              type:
                type: string
              primary:
                type: boolean
        active:
          type: boolean
          description: Membership state in the connector organization.
      required:
        - userName
    ScimGroup:
      type: object
      additionalProperties: true
      properties:
        schemas:
          type: array
          items:
            type: string
        displayName:
          type: string
        externalId:
          type: string
        members:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
      required:
        - displayName
    ScimPatchOp:
      type: object
      additionalProperties: true
      properties:
        schemas:
          type: array
          items:
            type: string
        Operations:
          type: array
          items:
            type: object
            properties:
              op:
                type: string
                description: add, replace or remove (case-insensitive).
              path:
                type: string
              value: {}
            required:
              - op
      required:
        - Operations
    ScimErrorDocument:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        status:
          type: string
        scimType:
          type: string
        detail:
          type: string
      required:
        - schemas
        - status
    ProvisioningConnectorInput:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        kind:
          type: string
          enum:
            - scim_inbound
        allowed_resource_types:
          type: array
          items:
            type: string
            enum:
              - User
              - Group
        role_ceiling_ids:
          type: array
          items:
            type: string
          description: Roles the connector may ever grant; within the creator own ceiling.
        group_role_mappings:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Approved mappings from SCIM group display names to role IDs within the ceiling.
        default_role_id:
          type: string
        config:
          type: object
          additionalProperties: true
      required:
        - name
    ProvisioningConnector:
      type: object
      properties:
        id:
          type: string
        organization_id:
          type: string
        name:
          type: string
        kind:
          type: string
        state:
          type: string
          enum:
            - active
            - disabled
        allowed_resource_types:
          type: array
          items:
            type: string
        role_ceiling_ids:
          type: array
          items:
            type: string
        group_role_mappings:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        default_role_id:
          type: string
        config:
          type: object
          additionalProperties: true
        last_sync_at:
          type: string
          format: date-time
        last_error:
          type: string
        stats:
          type: object
          additionalProperties: true
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - state
        - version
    WorkloadTrustInput:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          maxLength: 100
        profile:
          type: string
          enum:
            - generic
            - github_actions
            - kubernetes
            - spiffe
        issuer:
          type: string
          description: >-
            https issuer the assertion's iss must equal (github_actions defaults to
            https://token.actions.githubusercontent.com; spiffe defaults to spiffe://<trust domain> for JWT-SVIDs
            without iss).
        jwks_uri:
          type: string
        jwks:
          type: object
          description: Inline JSON Web Key Set of the issuer's public signing keys (1 to 20).
        audience:
          type: string
          description: The exact audience the assertion must carry (in aud, string or array).
        subject:
          type: string
          description: Exact subject, or a prefix ending in * where the profile allows it.
        claim_constraints:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Claims that must have one of the listed values; nested claims use / (for example kubernetes.io/namespace).
            iss, sub, aud, exp, nbf, iat and jti are not allowed here.
        algorithms:
          type: array
          items:
            type: string
            enum:
              - RS256
              - PS256
              - ES256
              - ES384
              - EdDSA
        max_assertion_lifetime_seconds:
          type: integer
          minimum: 60
          maximum: 86400
          description: Longest accepted exp minus iat (default 3600).
        require_jti:
          type: boolean
          description: >-
            Refuse assertions without jti (default true for github_actions). A jti, when present, is single-use per
            trust.
        state:
          type: string
          enum:
            - active
            - disabled
      required:
        - name
        - audience
        - subject
    WorkloadTrust:
      type: object
      properties:
        id:
          type: string
        client_id:
          type: string
          description: The client's internal reference.
        name:
          type: string
        profile:
          type: string
        issuer:
          type: string
        jwks_uri:
          type: string
        jwks:
          type: object
        audience:
          type: string
        subject:
          type: string
        claim_constraints:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        algorithms:
          type: array
          items:
            type: string
        max_assertion_lifetime_seconds:
          type: integer
        require_jti:
          type: boolean
        state:
          type: string
        version:
          type: integer
        created_by_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
    RegistrationToken:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
            - initial
            - registration
        description:
          type: string
        allowed_scopes:
          type: array
          items:
            type: object
            properties:
              resource_id:
                type: string
              scopes:
                type: array
                items:
                  type: string
        project_id:
          type: string
        max_uses:
          type: integer
        uses:
          type: integer
        expires_at:
          type: string
          format: date-time
        state:
          type: string
          enum:
            - active
            - expired
            - revoked
            - exhausted
          description: 'expired: an initial access token past its expires_at (refused at registration; it can still be revoked).'
        created_by_id:
          type: string
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
    ResourceType:
      type: object
      properties:
        id:
          type: string
        resource_id:
          type: string
        name:
          type: string
        relations:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              subject_types:
                type: array
                items:
                  type: string
              implied_by:
                type: array
                items:
                  type: string
        permissions:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        shareable_relations:
          type: array
          items:
            type: string
        share_permission:
          type: string
        version:
          type: integer
        created_by_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ResourceShare:
      type: object
      properties:
        id:
          type: string
        organization_id:
          type: string
        resource_type:
          type: string
        object_id:
          type: string
        relation:
          type: string
        owner_user_id:
          type: string
        recipient_user_id:
          type: string
        state:
          type: string
          enum:
            - pending
            - accepted
            - declined
            - revoked
            - expired
        message:
          type: string
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        decided_at:
          type: string
          format: date-time
    ElevationEligibility:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: string
        role_id:
          type: string
        role_name:
          type: string
        scope:
          type: object
          properties:
            type:
              type: string
            id:
              type: string
        max_duration_seconds:
          type: integer
        requires_approval:
          type: boolean
        state:
          type: string
          enum:
            - active
            - revoked
        created_by_id:
          type: string
        created_at:
          type: string
          format: date-time
    Elevation:
      type: object
      properties:
        id:
          type: string
        eligibility_id:
          type: string
        user_id:
          type: string
        role_id:
          type: string
        role_name:
          type: string
        scope:
          type: object
          properties:
            type:
              type: string
            id:
              type: string
        reason:
          type: string
        duration_seconds:
          type: integer
        state:
          type: string
          enum:
            - pending
            - active
            - rejected
            - ended
            - expired
            - cancelled
        requested_at:
          type: string
          format: date-time
        decided_by_id:
          type: string
        decided_at:
          type: string
          format: date-time
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        assignment_id:
          type: string
    AccessReview:
      type: object
      properties:
        id:
          type: string
        organization_id:
          type: string
        name:
          type: string
        description:
          type: string
        state:
          type: string
          enum:
            - open
            - closed
            - cancelled
        reviewer_ids:
          type: array
          items:
            type: string
        role_ids:
          type: array
          items:
            type: string
        privileged_only:
          type: boolean
        on_no_decision:
          type: string
          enum:
            - keep
            - revoke
        due_at:
          type: string
          format: date-time
        overdue:
          type: boolean
        items_total:
          type: integer
        items_decided:
          type: integer
        summary:
          type: object
          additionalProperties:
            type: integer
        created_by_id:
          type: string
        created_at:
          type: string
          format: date-time
        closed_by_id:
          type: string
        closed_at:
          type: string
          format: date-time
    AccessReviewItem:
      type: object
      properties:
        id:
          type: string
        assignment_id:
          type: string
        role_id:
          type: string
        role_name:
          type: string
        subject:
          type: object
          properties:
            type:
              type: string
            id:
              type: string
        scope:
          type: object
          properties:
            type:
              type: string
            id:
              type: string
        source:
          type: string
        granted_by_id:
          type: string
        granted_at:
          type: string
          format: date-time
        privileged:
          type: boolean
        decision:
          type: string
          enum:
            - keep
            - revoke
        decided_by_id:
          type: string
        decided_at:
          type: string
          format: date-time
        comment:
          type: string
        outcome:
          type: string
          enum:
            - kept
            - revoked
            - already_removed
            - revoke_failed
        applied_at:
          type: string
          format: date-time
    CertificateTrustAnchor:
      type: object
      properties:
        id:
          type: string
        purpose:
          type: string
          enum:
            - client
            - user
        name:
          type: string
        certificate_pem:
          type: string
        subject:
          type: string
        fingerprint:
          type: string
          description: base64url SHA-256 of the authority certificate.
        not_after:
          type: string
          format: date-time
        revocation:
          type: string
          enum:
            - none
            - crl
        crl_next_update:
          type: string
          format: date-time
        map_san_email:
          type: boolean
        multi_factor:
          type: boolean
        state:
          type: string
        created_by_id:
          type: string
        created_at:
          type: string
          format: date-time
    CertificateBinding:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: string
        anchor_id:
          type: string
        issuer_dn:
          type: string
        subject_dn:
          type: string
        state:
          type: string
        created_by_id:
          type: string
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
    AuthFlowDefinition:
      type: object
      description: The realm policy authentication_flow member (AUT-012).
      additionalProperties: true
      properties:
        rules:
          type: array
          maxItems: 50
          items:
            type: object
            additionalProperties: true
        challenge_provider:
          type: string
        email_code_alternative:
          type: boolean
    AuthFlowFinding:
      type: object
      required:
        - severity
        - code
        - rule
        - index
        - message
      properties:
        severity:
          type: string
          enum:
            - error
            - warning
        code:
          type: string
          enum:
            - bypass
            - unreachable
            - partial_bypass
            - skip_on_missing
            - deny_all
        rule:
          type: string
        index:
          type: integer
        by:
          type: string
        message:
          type: string
    AuthFlowAnalysis:
      type: object
      required:
        - errors
        - warnings
        - unreachable_rules
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/AuthFlowFinding'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/AuthFlowFinding'
        unreachable_rules:
          type: array
          items:
            type: string
    AuthFlowResult:
      type: object
      required:
        - outcome
      properties:
        outcome:
          type: string
          enum:
            - allow
            - review
            - challenge
            - require_mfa
            - require_phishing_resistant
            - deny
        rule:
          type: string
        missing_signals:
          type: array
          items:
            type: string
    AuthFlowCase:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        client_id:
          type: string
        organization_id:
          type: string
        method:
          type: string
        resources:
          type: array
          items:
            type: string
        ip:
          type: string
        known_device:
          type: boolean
        failed_attempts:
          type: integer
        risk:
          type: string
          enum:
            - low
            - medium
            - high
        risk_partial:
          type: boolean
        privileged:
          type: boolean
        assurance:
          type: string
    AuthFlowRevision:
      type: object
      required:
        - revision
        - state
        - definition
        - definition_hash
        - base_hash
        - analysis
        - created_by
        - created_at
      properties:
        revision:
          type: integer
        state:
          type: string
          enum:
            - draft
            - published
            - superseded
            - discarded
        definition:
          $ref: '#/components/schemas/AuthFlowDefinition'
        definition_hash:
          type: string
        base_hash:
          type: string
        note:
          type: string
        analysis:
          $ref: '#/components/schemas/AuthFlowAnalysis'
        rollback_of:
          type: integer
        policy_revision:
          type: integer
        created_by:
          type: object
        created_at:
          type: string
          format: date-time
        published_by:
          type: object
        published_at:
          type: string
          format: date-time
    SSFConfiguration:
      type: object
      properties:
        spec_version:
          type: string
        issuer:
          type: string
        jwks_uri:
          type: string
        delivery_methods_supported:
          type: array
          items:
            type: string
        configuration_endpoint:
          type: string
        status_endpoint:
          type: string
        add_subject_endpoint:
          type: string
        remove_subject_endpoint:
          type: string
        verification_endpoint:
          type: string
        authorization_schemes:
          type: array
          items:
            type: object
        default_subjects:
          type: string
        events_supported:
          type: array
          items:
            type: string
    SSFDelivery:
      type: object
      additionalProperties: false
      required:
        - method
      properties:
        method:
          type: string
          enum:
            - urn:ietf:rfc:8935
            - urn:ietf:rfc:8936
        endpoint_url:
          type: string
          description: Push target (receiver-supplied); for poll, assigned by the transmitter.
        authorization_header:
          type: string
          x-secret: true
          description: Write-only. Sent as the Authorization header of each push; stored encrypted and never returned.
    SSFStreamInput:
      type: object
      additionalProperties: false
      properties:
        stream_id:
          type: string
        delivery:
          $ref: '#/components/schemas/SSFDelivery'
        events_requested:
          type: array
          maxItems: 50
          items:
            type: string
        description:
          type: string
          maxLength: 500
        subject_scope:
          type: string
          enum:
            - client_users
            - listed
        iss: {}
        aud: {}
        events_supported: {}
        events_delivered: {}
        min_verification_interval: {}
        status: {}
        reason: {}
        client_id: {}
        created_at: {}
        updated_at: {}
    SSFStream:
      type: object
      required:
        - stream_id
        - iss
        - aud
        - delivery
        - events_supported
        - events_requested
        - events_delivered
        - min_verification_interval
        - subject_scope
        - status
      properties:
        stream_id:
          type: string
        iss:
          type: string
        aud:
          type: string
        delivery:
          $ref: '#/components/schemas/SSFDelivery'
        events_supported:
          type: array
          items:
            type: string
        events_requested:
          type: array
          items:
            type: string
        events_delivered:
          type: array
          items:
            type: string
        description:
          type: string
        min_verification_interval:
          type: integer
        subject_scope:
          type: string
          enum:
            - client_users
            - listed
            - all
        status:
          type: string
          enum:
            - enabled
            - paused
            - disabled
        reason:
          type: string
        client_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SAMLEndpoint:
      type: object
      additionalProperties: false
      properties:
        binding:
          type: string
          enum:
            - urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
            - urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
          description: 'Assertion consumer services: HTTP-POST only (default). Logout endpoints: HTTP-Redirect or HTTP-POST.'
        url:
          type: string
          format: uri
        response_url:
          type: string
          format: uri
          description: 'Logout endpoints: where LogoutResponses go (default url).'
        index:
          type: integer
          description: Assertion consumer service index (assigned in order when all are 0).
        is_default:
          type: boolean
          description: The default assertion consumer service (the first when none is marked).
      required:
        - url
    SAMLCertificate:
      type: object
      additionalProperties: false
      properties:
        pem:
          type: string
          description: PEM certificate.
        sha256_fingerprint:
          type: string
        subject:
          type: string
        not_before:
          type: string
          format: date-time
        not_after:
          type: string
          format: date-time
      required:
        - pem
        - sha256_fingerprint
        - not_before
        - not_after
    SAMLAttributeMapping:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          maxLength: 256
        name_format:
          type: string
          enum:
            - urn:oasis:names:tc:SAML:2.0:attrname-format:basic
            - urn:oasis:names:tc:SAML:2.0:attrname-format:uri
            - urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
          description: 'Default: uri when the name contains a colon, basic otherwise.'
        friendly_name:
          type: string
          maxLength: 128
        source:
          type: string
          enum:
            - email
            - email_verified
            - name
            - given_name
            - family_name
            - preferred_username
            - locale
            - zoneinfo
            - phone_number
            - user_id
            - subject
            - organization_id
            - static
          description: >-
            email and phone_number release verified identifiers only; subject is the NameID value; an empty value is not
            released.
        value:
          type: string
          maxLength: 512
          description: Static attributes only; never under a protected identity name (SAML-006).
      required:
        - name
        - source
    SAMLIdentityProviderEndpoints:
      type: object
      additionalProperties: false
      properties:
        entity_id:
          type: string
          description: The realm issuer.
        metadata_url:
          type: string
        sso_url:
          type: string
        slo_url:
          type: string
      required:
        - entity_id
        - metadata_url
        - sso_url
        - slo_url
    SAMLApplication:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        entity_id:
          type: string
        client_ref:
          type: string
          description: Backing client (protocol saml).
        client_id:
          type: string
        state:
          type: string
          enum:
            - active
            - suspended
            - decommissioned
        name:
          type: string
          maxLength: 200
        description:
          type: string
        organization_id:
          type: string
          description: Only that organization's active members receive assertions; its policies apply to the sign-in.
        project_id:
          type: string
        environment:
          type: string
          enum:
            - production
            - staging
            - development
        first_party:
          type: boolean
        consent_mode:
          type: string
          enum:
            - required
            - preauthorized
          description: 'Default: preauthorized for first-party, required otherwise.'
        consent_terms_version:
          type: string
        require_mfa:
          type: boolean
        max_session_age_seconds:
          type: integer
        allow_remember_me:
          type: boolean
        login_ui_url:
          type: string
          description: 'Login interface for this application (default: the realm''s).'
        assertion_consumer_services:
          type: array
          items:
            $ref: '#/components/schemas/SAMLEndpoint'
        single_logout_services:
          type: array
          items:
            $ref: '#/components/schemas/SAMLEndpoint'
        require_signed_requests:
          type: boolean
          description: 'AuthnRequests must be signed with a registered certificate (default: true when certificates are registered).'
        name_id_format:
          type: string
          enum:
            - urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
            - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
            - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
            - urn:oasis:names:tc:SAML:2.0:nameid-format:transient
          description: >-
            persistent (default): opaque, stable and different per application; emailAddress: the verified email only;
            unspecified: the account ID; transient: new per assertion.
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/SAMLAttributeMapping'
        sign_response:
          type: boolean
          description: Sign the Response (default true).
        sign_assertion:
          type: boolean
          description: Sign the Assertion (default true).
        signature_algorithm:
          type: string
          enum:
            - http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
            - http://www.w3.org/2001/04/xmldsig-more#rsa-sha384
            - http://www.w3.org/2001/04/xmldsig-more#rsa-sha512
        allow_idp_initiated:
          type: boolean
          description: Allow unsolicited (IdP-initiated) responses (SAML-007); default false.
        idp_initiated_relay_state:
          type: string
          maxLength: 1024
        clock_skew_seconds:
          type: integer
          description: Default 120; at most saml.max_clock_skew.
        assertion_lifetime_seconds:
          type: integer
          description: Default 300; 60..1800.
        additional_audiences:
          type: array
          items:
            type: string
          description: Further Audience values (at most 5).
        encrypt_assertions:
          type: boolean
          description: Encrypt assertions (sign, then encrypt) to the encryption certificate.
        data_encryption_algorithm:
          type: string
          enum:
            - http://www.w3.org/2009/xmlenc11#aes256-gcm
            - http://www.w3.org/2009/xmlenc11#aes128-gcm
          description: Default aes256-gcm. AES-CBC is not offered (SAML-009).
        key_transport_algorithm:
          type: string
          enum:
            - http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
            - http://www.w3.org/2009/xmlenc11#rsa-oaep
          description: Default rsa-oaep-mgf1p; xmlenc11 rsa-oaep uses SHA-256 and MGF1-SHA-256. RSA PKCS#1 v1.5 is not offered.
        authn_context_map:
          type: object
          additionalProperties:
            type: string
          description: >-
            AuthnContextClassRef -> local ACR (urn:proudauth:acr:...), extending the built-in mapping
            (PasswordProtectedTransport, Password, unspecified = single factor; MobileTwoFactorContract, TimeSyncToken,
            multipleauthn, REFEDS MFA = mfa).
        signing_certificates:
          type: array
          items:
            $ref: '#/components/schemas/SAMLCertificate'
        encryption_certificate:
          $ref: '#/components/schemas/SAMLCertificate'
        identity_provider:
          $ref: '#/components/schemas/SAMLIdentityProviderEndpoints'
        version:
          type: integer
          format: int64
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - entity_id
        - client_ref
        - client_id
        - state
        - assertion_consumer_services
        - name_id_format
        - attributes
        - signing_certificates
        - identity_provider
        - version
    SAMLApplicationInput:
      type: object
      additionalProperties: false
      properties:
        entity_id:
          type: string
          description: Required unless metadata_xml supplies it.
        metadata_xml:
          type: string
          description: Uploaded SP metadata (EntityDescriptor with an SPSSODescriptor).
        name:
          type: string
          maxLength: 200
        description:
          type: string
        organization_id:
          type: string
          description: Only that organization's active members receive assertions; its policies apply to the sign-in.
        project_id:
          type: string
        environment:
          type: string
          enum:
            - production
            - staging
            - development
        first_party:
          type: boolean
        consent_mode:
          type: string
          enum:
            - required
            - preauthorized
          description: 'Default: preauthorized for first-party, required otherwise.'
        consent_terms_version:
          type: string
        require_mfa:
          type: boolean
        max_session_age_seconds:
          type: integer
        allow_remember_me:
          type: boolean
        login_ui_url:
          type: string
          description: 'Login interface for this application (default: the realm''s).'
        assertion_consumer_services:
          type: array
          items:
            $ref: '#/components/schemas/SAMLEndpoint'
        single_logout_services:
          type: array
          items:
            $ref: '#/components/schemas/SAMLEndpoint'
        require_signed_requests:
          type: boolean
          description: 'AuthnRequests must be signed with a registered certificate (default: true when certificates are registered).'
        name_id_format:
          type: string
          enum:
            - urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
            - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
            - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
            - urn:oasis:names:tc:SAML:2.0:nameid-format:transient
          description: >-
            persistent (default): opaque, stable and different per application; emailAddress: the verified email only;
            unspecified: the account ID; transient: new per assertion.
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/SAMLAttributeMapping'
        sign_response:
          type: boolean
          description: Sign the Response (default true).
        sign_assertion:
          type: boolean
          description: Sign the Assertion (default true).
        signature_algorithm:
          type: string
          enum:
            - http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
            - http://www.w3.org/2001/04/xmldsig-more#rsa-sha384
            - http://www.w3.org/2001/04/xmldsig-more#rsa-sha512
        allow_idp_initiated:
          type: boolean
          description: Allow unsolicited (IdP-initiated) responses (SAML-007); default false.
        idp_initiated_relay_state:
          type: string
          maxLength: 1024
        clock_skew_seconds:
          type: integer
          description: Default 120; at most saml.max_clock_skew.
        assertion_lifetime_seconds:
          type: integer
          description: Default 300; 60..1800.
        additional_audiences:
          type: array
          items:
            type: string
          description: Further Audience values (at most 5).
        encrypt_assertions:
          type: boolean
          description: Encrypt assertions (sign, then encrypt) to the encryption certificate.
        data_encryption_algorithm:
          type: string
          enum:
            - http://www.w3.org/2009/xmlenc11#aes256-gcm
            - http://www.w3.org/2009/xmlenc11#aes128-gcm
          description: Default aes256-gcm. AES-CBC is not offered (SAML-009).
        key_transport_algorithm:
          type: string
          enum:
            - http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
            - http://www.w3.org/2009/xmlenc11#rsa-oaep
          description: Default rsa-oaep-mgf1p; xmlenc11 rsa-oaep uses SHA-256 and MGF1-SHA-256. RSA PKCS#1 v1.5 is not offered.
        authn_context_map:
          type: object
          additionalProperties:
            type: string
          description: >-
            AuthnContextClassRef -> local ACR (urn:proudauth:acr:...), extending the built-in mapping
            (PasswordProtectedTransport, Password, unspecified = single factor; MobileTwoFactorContract, TimeSyncToken,
            multipleauthn, REFEDS MFA = mfa).
        signing_certificates:
          type: array
          items:
            type: string
          description: PEM or base64 DER certificates for request and logout signatures.
        encryption_certificate:
          type: string
          description: PEM or base64 DER RSA certificate for encrypted assertions (requires encrypt_assertions).
      required:
        - name
    SAMLConnectionSettings:
      type: object
      additionalProperties: false
      properties:
        idp_entity_id:
          type: string
        sso_url:
          type: string
          description: HTTP-Redirect single sign-on endpoint.
        sp_entity_id:
          type: string
          description: Overrides the default service provider entity ID.
        sign_authn_requests:
          type: boolean
          description: Sign AuthnRequests with the realm SAML key (default true).
        require_signed_assertions:
          type: boolean
          description: Refuse assertions covered only by the response signature.
        name_id_format:
          type: string
          enum:
            - urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
            - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
            - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
            - urn:oasis:names:tc:SAML:2.0:nameid-format:transient
        subject_attribute:
          type: string
          description: Take the stable subject from this attribute instead of the NameID (required for transient NameIDs).
        email_attribute:
          type: string
          description: 'Email attribute (default: the NameID when its format is emailAddress).'
        trust_email_verified:
          type: boolean
          description: Treat the asserted email as verified (SAML has no verification flag).
        trusted_authn_contexts:
          type: array
          items:
            type: string
          description: AuthnContextClassRef values that mean MFA, used with trust_upstream_mfa (FED-009).
        requested_authn_contexts:
          type: array
          items:
            type: string
          description: Sent as RequestedAuthnContext Comparison=minimum.
        force_authn:
          type: boolean
        clock_skew_seconds:
          type: integer
          description: Default 120; at most saml.max_clock_skew.
        signing_certificates:
          type: array
          items:
            $ref: '#/components/schemas/SAMLCertificate'
    SAMLServiceProvider:
      description: This realm's service provider side of the connection, to register with the identity provider.
      type: object
      additionalProperties: false
      properties:
        entity_id:
          type: string
        acs_url:
          type: string
        metadata_url:
          type: string
      required:
        - entity_id
        - acs_url
        - metadata_url
    SAMLConnection:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        organization_id:
          type: string
        alias:
          type: string
        display_name:
          type: string
          maxLength: 100
        state:
          type: string
          enum:
            - active
            - disabled
        linking_policy:
          type: string
          enum:
            - verify_existing
            - trusted_verified_email
            - create_only
        jit_provisioning:
          type: boolean
        jit_default_role_id:
          type: string
        trust_upstream_mfa:
          type: boolean
        allowed_email_domains:
          type: array
          items:
            type: string
        claim_mapping:
          $ref: '#/components/schemas/ClaimMapping'
          description: Maps SAML attribute names to profile fields (default displayName, givenName, sn).
        saml:
          $ref: '#/components/schemas/SAMLConnectionSettings'
        service_provider:
          $ref: '#/components/schemas/SAMLServiceProvider'
        version:
          type: integer
          format: int64
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - alias
        - display_name
        - state
        - linking_policy
        - saml
        - service_provider
        - version
    SAMLConnectionInput:
      type: object
      additionalProperties: false
      properties:
        organization_id:
          type: string
        alias:
          type: string
        display_name:
          type: string
          maxLength: 100
        state:
          type: string
          enum:
            - active
            - disabled
        linking_policy:
          type: string
          enum:
            - verify_existing
            - trusted_verified_email
            - create_only
        jit_provisioning:
          type: boolean
        jit_default_role_id:
          type: string
        trust_upstream_mfa:
          type: boolean
        allowed_email_domains:
          type: array
          items:
            type: string
        claim_mapping:
          $ref: '#/components/schemas/ClaimMapping'
          description: Maps SAML attribute names to profile fields (default displayName, givenName, sn).
        metadata_xml:
          type: string
          description: Uploaded IdP metadata (EntityDescriptor with an IDPSSODescriptor).
        idp_entity_id:
          type: string
        sso_url:
          type: string
          description: HTTP-Redirect single sign-on endpoint.
        sp_entity_id:
          type: string
          description: Overrides the default service provider entity ID.
        sign_authn_requests:
          type: boolean
          description: Sign AuthnRequests with the realm SAML key (default true).
        require_signed_assertions:
          type: boolean
          description: Refuse assertions covered only by the response signature.
        name_id_format:
          type: string
          enum:
            - urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
            - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
            - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
            - urn:oasis:names:tc:SAML:2.0:nameid-format:transient
        subject_attribute:
          type: string
          description: Take the stable subject from this attribute instead of the NameID (required for transient NameIDs).
        email_attribute:
          type: string
          description: 'Email attribute (default: the NameID when its format is emailAddress).'
        trust_email_verified:
          type: boolean
          description: Treat the asserted email as verified (SAML has no verification flag).
        trusted_authn_contexts:
          type: array
          items:
            type: string
          description: AuthnContextClassRef values that mean MFA, used with trust_upstream_mfa (FED-009).
        requested_authn_contexts:
          type: array
          items:
            type: string
          description: Sent as RequestedAuthnContext Comparison=minimum.
        force_authn:
          type: boolean
        clock_skew_seconds:
          type: integer
          description: Default 120; at most saml.max_clock_skew.
        signing_certificates:
          type: array
          items:
            type: string
          description: Trusted PEM or base64 DER certificates (at most 4; list two to overlap a rollover).
      required:
        - alias
        - display_name
    SAMLSigningKey:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        state:
          type: string
          enum:
            - pending
            - active
            - retiring
            - retired
        published:
          type: boolean
          description: Listed in metadata now.
        certificate:
          $ref: '#/components/schemas/SAMLCertificate'
        created_at:
          type: string
          format: date-time
        activated_at:
          type: string
          format: date-time
        retiring_at:
          type: string
          format: date-time
        publish_until:
          type: string
          format: date-time
      required:
        - id
        - state
        - published
        - certificate
        - created_at
    LDAPConnectorConfig:
      type: object
      additionalProperties: false
      description: >-
        LDAP/Active Directory connector configuration (PROV-011). Defaults follow the dialect. Never contains the bind
        password.
      properties:
        endpoints:
          type: array
          minItems: 1
          maxItems: 8
          items:
            type: string
          description: >-
            ldaps://host[:port] or ldap://host[:port] URLs, tried in order; the next one is used only after a transport
            failure (connect, TLS, timeout, server busy/unavailable), never after an answer such as invalid credentials.
            Referrals are never followed (PROV-014).
        start_tls:
          type: boolean
          default: true
          description: Upgrade ldap:// endpoints with StartTLS before any credential is sent; false only in development mode.
        ca_certificates_pem:
          type: string
          maxLength: 65536
          description: >-
            Additional trusted roots for this connector (PEM). Server certificates are always verified, including the
            host name.
        connect_timeout_seconds:
          type: integer
          minimum: 0
          maximum: 60
          description: '0: directory.connect_timeout.'
        operation_timeout_seconds:
          type: integer
          minimum: 0
          maximum: 120
          description: '0: directory.operation_timeout.'
        bind_dn:
          type: string
          description: Service account DN.
        dialect:
          type: string
          enum:
            - openldap
            - active_directory
          default: openldap
        user_base_dn:
          type: string
        user_scope:
          type: string
          enum:
            - sub
            - one
          default: sub
        user_filter:
          type: string
          description: >-
            RFC 4515 filter; default (objectClass=inetOrgPerson) or, for Active Directory,
            (&(objectCategory=person)(objectClass=user)).
        id_attribute:
          type: string
          description: 'Immutable entry identifier: entryUUID (default) or objectGUID (Active Directory).'
        login_attributes:
          type: array
          maxItems: 4
          items:
            type: string
          description: >-
            Attributes a sign-in identifier is matched against for first sign-in provisioning; the identifier is escaped
            (RFC 4515).
        attribute_mapping:
          type: object
          additionalProperties:
            type: string
          description: >-
            Local attribute (username, email, display_name, given_name, family_name, locale, zoneinfo, profile.<name>)
            to directory attribute.
        mode:
          type: string
          enum:
            - read_only
            - import_only
            - write_back
          default: read_only
          description: >-
            read_only: the directory owns the mapped attributes (local edits refused); import_only: attributes are
            imported at creation and locally owned afterwards (differences reported as divergence); write_back:
            write_back_attributes are editable and written to the directory first. The directory always owns the
            password and the account lifecycle (PROV-013).
        attribute_authority:
          type: object
          additionalProperties:
            type: string
            enum:
              - directory
              - local
          description: Per-attribute override of the mode's authority.
        write_back_attributes:
          type: array
          items:
            type: string
          description: write_back mode only; never username, email or the password.
        disabled_attribute:
          type: string
          description: Marks disabled entries outside Active Directory (whose userAccountControl is always honored).
        disabled_values:
          type: array
          items:
            type: string
        change_tracking:
          type: string
          enum:
            - usn
            - modify_timestamp
            - none
          description: >-
            Incremental cursor: Active Directory uSNChanged (bound to the domain controller; another controller forces a
            full run), modifyTimestamp (re-reads a 5-minute overlap), or none.
        page_size:
          type: integer
          minimum: 1
          maximum: 5000
          default: 500
          description: Simple paged results (RFC 2696) page size.
        max_entries:
          type: integer
          minimum: 0
          maximum: 1000000
          description: '0: directory.max_entries_per_run.'
        group_base_dn:
          type: string
        group_filter:
          type: string
        group_name_attribute:
          type: string
        group_member_attribute:
          type: string
          enum:
            - member
            - uniqueMember
            - memberUid
        jit_provisioning:
          type: boolean
          default: false
          description: Import an account at its first successful sign-in (FED-015).
        incremental_interval_seconds:
          type: integer
          description: '0 or 60..604800: scheduled incremental runs.'
        full_interval_seconds:
          type: integer
          description: '0 or 300..2592000: scheduled full runs (deletion detection).'
        deletion_threshold_percent:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
          description: A full run refuses to deprovision more than this share of linked accounts without allow_mass_deprovision.
        deletion_threshold_count:
          type: integer
          minimum: 0
          description: 'Optional absolute cap on deprovisioning per run (0: none).'
        deprovision_action:
          type: string
          enum:
            - suspend_account
            - remove_membership
            - suspend_membership
            - report_only
          description: >-
            Realm connectors: suspend_account (default) or report_only — accounts are never deleted. Organization
            connectors: remove_membership (default), suspend_membership or report_only — only the organization's access
            changes (PROV-005).
      required:
        - endpoints
        - bind_dn
        - user_base_dn
    OutboundConnectorConfig:
      type: object
      additionalProperties: false
      description: Outbound SCIM 2.0 connector configuration (PROV-010). Never contains the bearer token.
      properties:
        base_url:
          type: string
          description: >-
            SCIM base URL (https outside development); checked against the egress policy at configuration and on every
            connection.
        allow_private_network:
          type: boolean
          default: false
          description: >-
            Allow a private destination where the operator policy (delivery.allow_private_webhooks or
            delivery.egress_allowlist) permits it.
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 60
          default: 10
        max_attempts:
          type: integer
          minimum: 1
          maximum: 20
          default: 8
          description: >-
            Attempts before a delivery is dead-lettered; retries back off exponentially with jitter and honor
            Retry-After.
        eligible_organization_ids:
          type: array
          items:
            type: string
          description: >-
            Realm connectors: push accounts with an active membership in one of these organizations (every non-guest
            account when empty).
        eligible_group_ids:
          type: array
          items:
            type: string
          description: 'Organization connectors: push only members of one of these groups.'
        exclude_created_via:
          type: array
          items:
            type: string
          description: >-
            Skip accounts by provenance (for example scim:<connector> for accounts an inbound connector created from the
            same system), preventing loops (PROV-017).
        attribute_mapping:
          type: object
          additionalProperties:
            type: string
          description: >-
            SCIM attribute (userName, displayName, name.givenName, name.familyName, emails, locale, timezone, title) to
            local source (username, email, display_name, given_name, family_name, locale, zoneinfo, user_id,
            profile.<name>). externalId is always the local account ID. Only verified emails are pushed.
        deprovision_action:
          type: string
          enum:
            - deactivate
            - delete
          default: deactivate
        push_group_ids:
          type: array
          items:
            type: string
          description: Organization groups pushed with the downstream IDs of their members.
        reconcile_interval_seconds:
          type: integer
          description: '0 or 300..2592000: scheduled reconciliation runs.'
      required:
        - base_url
    DirectoryConnectorInput:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        kind:
          type: string
          enum:
            - ldap
            - scim_outbound
        organization_id:
          type: string
          description: 'Realm API only: bind the connector to an organization.'
        config:
          oneOf:
            - $ref: '#/components/schemas/LDAPConnectorConfig'
            - $ref: '#/components/schemas/OutboundConnectorConfig'
          description: Kind-specific configuration.
        role_ceiling_ids:
          type: array
          items:
            type: string
          description: 'Organization connectors: roles the connector may ever grant, within the creator''s own ceiling.'
        group_role_mappings:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Approved mappings from directory group names or DNs to role IDs within the ceiling.
        default_role_id:
          type: string
        credential:
          type: string
          maxLength: 4096
          x-secret: true
          description: >-
            Write-only: bind password (ldap) or downstream bearer token (scim_outbound). Stored encrypted; never
            returned.
      required:
        - name
        - kind
        - config
        - credential
    DirectoryConnectorUpdate:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        kind:
          type: string
          description: Fixed after creation; must match when sent.
        organization_id:
          type: string
          description: Fixed after creation; must match when sent.
        config:
          oneOf:
            - $ref: '#/components/schemas/LDAPConnectorConfig'
            - $ref: '#/components/schemas/OutboundConnectorConfig'
        role_ceiling_ids:
          type: array
          items:
            type: string
        group_role_mappings:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        default_role_id:
          type: string
        credential:
          type: string
          description: Not accepted here; use PUT .../credential.
        state:
          type: string
          enum:
            - active
            - disabled
      required:
        - name
        - config
    DirectoryConnector:
      type: object
      properties:
        id:
          type: string
        organization_id:
          type: string
          description: Absent for realm-wide (workforce) connectors.
        name:
          type: string
        kind:
          type: string
          enum:
            - ldap
            - scim_outbound
        state:
          type: string
          enum:
            - active
            - disabled
        config:
          oneOf:
            - $ref: '#/components/schemas/LDAPConnectorConfig'
            - $ref: '#/components/schemas/OutboundConnectorConfig'
        role_ceiling_ids:
          type: array
          items:
            type: string
        group_role_mappings:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        default_role_id:
          type: string
        credential_set:
          type: boolean
        credential_set_at:
          type: string
          format: date-time
        last_sync_at:
          type: string
          format: date-time
        last_success_at:
          type: string
          format: date-time
        last_error:
          type: string
        consecutive_failures:
          type: integer
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - kind
        - state
        - config
        - credential_set
        - version
    DirectoryRunRequest:
      type: object
      additionalProperties: false
      properties:
        mode:
          type: string
          enum:
            - full
            - incremental
            - reconcile
          description: >-
            Directories: incremental (default; promoted to full without a usable cursor) or full (also detects
            deletions). Outbound connectors: reconcile.
        dry_run:
          type: boolean
          default: false
        allow_mass_deprovision:
          type: boolean
          default: false
        reason:
          type: string
          maxLength: 500
          description: Required (10+ characters) with allow_mass_deprovision.
    DirectoryRun:
      type: object
      properties:
        id:
          type: string
        connector_id:
          type: string
        organization_id:
          type: string
        job_id:
          type: string
        mode:
          type: string
          enum:
            - full
            - incremental
            - reconcile
        dry_run:
          type: boolean
        trigger:
          type: string
          enum:
            - manual
            - schedule
            - login
        state:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - failed
            - refused
            - cancelled
          description: 'refused: the deletion threshold stopped deprovisioning; other changes of the run were applied.'
        allow_mass_deprovision:
          type: boolean
        requested_by_type:
          type: string
        requested_by_id:
          type: string
        reason:
          type: string
        cursor_before:
          type: string
        cursor_after:
          type: string
        endpoint:
          type: string
          description: Host of the endpoint that served the run.
        counts:
          type: object
          additionalProperties:
            type: integer
          description: >-
            Totals per finding kind plus entries_seen, linked_accounts, deprovision_refused,
            incremental_promoted_to_full, findings_truncated, candidates.
        error:
          type: string
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
      required:
        - id
        - connector_id
        - mode
        - dry_run
        - state
        - counts
    DirectoryFinding:
      type: object
      properties:
        seq:
          type: integer
        kind:
          type: string
        reason:
          type: string
        external_id:
          type: string
        source_dn:
          type: string
        local_id:
          type: string
        attributes:
          type: array
          items:
            type: string
          description: Attribute names only, never values.
        applied:
          type: boolean
        detail:
          type: object
          additionalProperties: true
      required:
        - seq
        - kind
        - attributes
        - applied
    DirectoryEndpointHealth:
      type: object
      properties:
        last_ok_at:
          type: string
          format: date-time
        last_failure_at:
          type: string
          format: date-time
        last_failure_category:
          type: string
          description: connect, dns, tls, timeout, network, server_unavailable, egress_denied or service_bind_failed.
        consecutive_failures:
          type: integer
    DirectoryHealth:
      type: object
      properties:
        connector_id:
          type: string
        kind:
          type: string
        state:
          type: string
        status:
          type: string
          enum:
            - healthy
            - degraded
            - disabled
            - needs_configuration
            - needs_credential
        configuration_error:
          type: string
          description: >-
            Why an outbound connector cannot deliver (status needs_configuration), for example a legacy scim_outbound
            row without base_url.
        credential_set_at:
          type: string
          format: date-time
        last_sync_at:
          type: string
          format: date-time
        last_success_at:
          type: string
          format: date-time
        lag_seconds:
          type: integer
        consecutive_failures:
          type: integer
        last_error:
          type: string
        endpoints:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DirectoryEndpointHealth'
          description: Keyed by host:port.
        last_run:
          $ref: '#/components/schemas/DirectoryRun'
        managed_accounts:
          type: object
          additionalProperties:
            type: integer
          description: >-
            Linked accounts by source state (active, disabled, missing, deleted for erased accounts; deactivated for
            outbound).
        managed_groups:
          type: integer
        deliveries:
          type: object
          additionalProperties:
            type: integer
          description: Outbound deliveries by state.
        oldest_due_seconds:
          type: integer
        last_delivered_at:
          type: string
          format: date-time
        operator_actions:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
              actor_type:
                type: string
              actor_id:
                type: string
              at:
                type: string
                format: date-time
          description: The latest 20 operator actions.
      required:
        - connector_id
        - status
        - operator_actions
    DirectoryTestResult:
      type: object
      properties:
        ok:
          type: boolean
        endpoint:
          type: string
        error:
          type: string
        details:
          type: object
          additionalProperties: true
        checked_at:
          type: string
          format: date-time
      required:
        - ok
        - checked_at
    OutboundDelivery:
      type: object
      properties:
        id:
          type: string
        resource_type:
          type: string
          enum:
            - User
            - Group
        local_id:
          type: string
        trigger:
          type: string
        state:
          type: string
          enum:
            - pending
            - retrying
            - delivered
            - dead_letter
            - replayed
        attempts:
          type: integer
        operation:
          type: string
          enum:
            - create
            - update
            - deactivate
            - delete
            - noop
            - read
        last_status_code:
          type: integer
        last_error_category:
          type: string
          description: >-
            network_error, egress_denied, server_error, throttled, unauthorized, rejected, conflict, invalid_response,
            credential_unavailable or local_error.
        next_attempt_at:
          type: string
          format: date-time
        delivered_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - resource_type
        - local_id
        - state
        - attempts
    AttributeAuthority:
      type: object
      properties:
        source:
          oneOf:
            - type: 'null'
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - directory
                connector_id:
                  type: string
                name:
                  type: string
                organization_id:
                  type: string
                mode:
                  type: string
                state:
                  type: string
                  description: 'The linked entry''s state: active, disabled or missing.'
        attributes:
          type: object
          additionalProperties:
            type: string
            enum:
              - local
              - externally_managed
              - write_back
        operations:
          type: object
          additionalProperties:
            type: string
            enum:
              - local
              - externally_managed
              - write_back
          description: password_change, password_reset and reactivation.
      required:
        - source
        - attributes
        - operations
    TrustedAuthenticator:
      type: object
      required:
        - id
        - aaguid
        - description
        - root_certificates
        - created_at
      properties:
        id:
          type: string
        aaguid:
          type: string
        description:
          type: string
        root_certificates:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
    FederationTransfer:
      type: object
      required:
        - id
        - source_provider_id
        - target_provider_id
        - mode
        - state
        - reason
        - summary
        - created_by_id
        - created_at
        - version
      properties:
        id:
          type: string
        source_provider_id:
          type: string
        target_provider_id:
          type: string
        mode:
          type: string
          enum:
            - map
            - same_subject
        target_tenant:
          type: string
        state:
          type: string
          enum:
            - draft
            - approved
            - applied
            - cancelled
        reason:
          type: string
        summary:
          type: object
          description: Entry count by outcome, plus total.
          additionalProperties:
            type: integer
        created_by_id:
          type: string
        approved_by_id:
          type: string
        applied_by_id:
          type: string
        created_at:
          type: string
          format: date-time
        approved_at:
          type: string
          format: date-time
        applied_at:
          type: string
          format: date-time
        version:
          type: integer
    FederationTransferEntry:
      type: object
      required:
        - seq
        - source_subject
        - target_subject
        - outcome
      properties:
        seq:
          type: integer
        source_subject:
          type: string
        source_issuer:
          type: string
        target_subject:
          type: string
        target_tenant:
          type: string
        user_id:
          type: string
        outcome:
          type: string
          enum:
            - pending
            - ready
            - already_linked
            - missing_source
            - ambiguous_source
            - duplicate_source
            - duplicate_target
            - collision_target
            - collision_user
            - target_tenant_required
            - applied
        detail:
          type: string
    MigrationAdapter:
      additionalProperties: false
      properties:
        source:
          type: string
          enum:
            - keycloak
            - zitadel
            - supertokens
        product:
          type: string
        supported_versions:
          type: string
          examples:
            - 26.x
        tested_versions:
          type: array
          items:
            type: string
        export_format:
          type: string
        export_command:
          type: string
        converts:
          type: array
          items:
            type: string
        converts_with_loss:
          type: array
          items:
            type: string
        unsupported:
          type: array
          items:
            type: string
      required:
        - source
        - product
        - supported_versions
        - tested_versions
        - export_format
        - export_command
        - converts
        - converts_with_loss
        - unsupported
      type: object
    MigrationMapping:
      description: >-
        proudauth.migration-mapping.v1: the reviewed translation (MIG-005). organizations maps a source organization key
        (Keycloak org:<alias> or group:<path>, ZITADEL org:<id>, SuperTokens tenant:<id>) to the organization it
        becomes, or null to exclude it. roles maps a source role key (Keycloak realm-role:<name>,
        client-role:<client>:<role>, group:<path>; ZITADEL org-member:<ROLE>, project-member:<project id>:<ROLE>,
        project-role:<project id>:<key>; SuperTokens role:<name>) to realm-wide organization roles; an unlisted key is
        reported unsupported and grants nothing.
      additionalProperties: false
      properties:
        format:
          type: string
          enum:
            - proudauth.migration-mapping.v1
        organizations:
          type: object
          additionalProperties:
            type:
              - object
              - 'null'
            additionalProperties: false
            properties:
              slug:
                type: string
                pattern: ^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$
              display_name:
                type: string
              note:
                type: string
            required:
              - slug
        membership_roles:
          type: array
          items:
            type: string
        roles:
          type: object
          additionalProperties:
            type:
              - object
              - 'null'
            additionalProperties: false
            properties:
              organization:
                type: string
                description: Target organization slug; without it the roles apply in the source grant's own scope.
              roles:
                type: array
                items:
                  type: string
              note:
                type: string
            required:
              - roles
      type: object
    MigrationEntityReport:
      additionalProperties: false
      properties:
        total:
          type: integer
        converted:
          type: integer
        converted_with_loss:
          type: integer
        unsupported:
          type: integer
        ignored:
          type: integer
        reasons:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              outcome:
                type: string
                enum:
                  - converted_with_loss
                  - unsupported
                  - ignored
              reason:
                type: string
              count:
                type: integer
            required:
              - outcome
              - reason
              - count
      required:
        - total
        - converted
        - converted_with_loss
        - unsupported
        - ignored
      type: object
    MigrationReport:
      description: >-
        proudauth.migration-report.v1, the capability report of one conversion (MIG-018). Records are named by source ID
        only.
      additionalProperties: false
      properties:
        format:
          type: string
          enum:
            - proudauth.migration-report.v1
        generated_at:
          type: string
          format: date-time
        source:
          type: object
          additionalProperties: false
          properties:
            product:
              type: string
            source:
              type: string
            version:
              type: string
            tested_versions:
              type: array
              items:
                type: string
            realm:
              type: string
          required:
            - product
            - source
            - version
            - tested_versions
        source_system:
          type: string
        options:
          type: object
          additionalProperties: false
          properties:
            import_totp:
              type: boolean
            keep_attributes:
              type: boolean
            mapping_given:
              type: boolean
          required:
            - import_totp
            - keep_attributes
            - mapping_given
        summary:
          type: object
          additionalProperties: false
          properties:
            users:
              type: integer
            users_to_import:
              type: integer
            passwords_migrated:
              type: integer
            password_resets_required:
              type: integer
            totp_migrated:
              type: integer
            mfa_reenrollments_required:
              type: integer
            suspended_accounts:
              type: integer
            organizations:
              type: integer
            memberships:
              type: integer
            role_assignments:
              type: integer
            untranslated_role_grants:
              type: integer
          required:
            - users
            - users_to_import
            - passwords_migrated
            - password_resets_required
            - totp_migrated
            - mfa_reenrollments_required
            - suspended_accounts
            - organizations
            - memberships
            - role_assignments
            - untranslated_role_grants
        entities:
          type: object
          description: >-
            Per entity type (users, service_accounts, organizations, groups, tenants, memberships, role_assignments,
            role_definitions, password_credentials, totp_factors, webauthn_credentials, recovery_codes,
            other_credentials, federated_identities, phone_numbers, attributes, required_actions, clients,
            identity_providers, authentication_flows, realm_policies, user_federation, client_scopes, projects,
            project_grants, actions, keys, other_configuration, sessions).
          additionalProperties:
            $ref: '#/components/schemas/MigrationEntityReport'
        mapping:
          type: object
          additionalProperties: false
          properties:
            organizations:
              type: array
              items:
                type: object
                additionalProperties: false
                properties:
                  key:
                    type: string
                  name:
                    type: string
                  status:
                    type: string
                    enum:
                      - auto
                      - mapped
                      - excluded
                      - not_an_organization
                  slug:
                    type: string
                  members:
                    type: integer
                required:
                  - key
                  - name
                  - status
                  - members
            roles:
              type: array
              items:
                type: object
                additionalProperties: false
                properties:
                  key:
                    type: string
                  note:
                    type: string
                  grants:
                    type: integer
                  status:
                    type: string
                    enum:
                      - mapped
                      - no_roles
                      - untranslated
                      - ignored
                  organization:
                    type: string
                  roles:
                    type: array
                    items:
                      type: string
                required:
                  - key
                  - grants
                  - status
            unknown_keys:
              type: array
              items:
                type: string
          required:
            - organizations
            - roles
        items:
          type: array
          description: Every source item that was not simply converted, with its reasons.
          items:
            type: object
            additionalProperties: false
            properties:
              entity:
                type: string
              source_id:
                type: string
              outcome:
                type: string
                enum:
                  - converted_with_loss
                  - unsupported
                  - ignored
              reasons:
                type: array
                items:
                  type: string
            required:
              - entity
              - source_id
              - outcome
              - reasons
        notes:
          type: array
          items:
            type: string
        import:
          type: object
          description: Filled by identity-cli migrate-from after a dry run or an import.
          additionalProperties: false
          properties:
            dry_run:
              type: boolean
            jobs:
              type: array
              items:
                type: string
            counts:
              type: object
              additionalProperties:
                type: integer
            totals:
              type: object
              additionalProperties:
                type: integer
            organizations:
              type: array
              items:
                type: object
                additionalProperties: false
                properties:
                  slug:
                    type: string
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - exists
                      - created
                      - will_create
                      - conflict
                  detail:
                    type: string
                required:
                  - slug
                  - status
            records:
              type: array
              items:
                type: object
                additionalProperties: false
                properties:
                  source_id:
                    type: string
                  status:
                    type: string
                  user_id:
                    type: string
                  error:
                    type: string
                required:
                  - source_id
                  - status
            reconciliation:
              type: object
              additionalProperties: true
          required:
            - dry_run
            - jobs
            - counts
            - totals
            - organizations
      required:
        - format
        - generated_at
        - source
        - source_system
        - options
        - summary
        - entities
        - mapping
        - items
      type: object
    OrganizationRelationship:
      type: object
      required:
        - id
        - kind
        - source_organization_id
        - target_organization_id
        - state
        - created_by
        - created_at
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
            - parent_child
            - partner
        source_organization_id:
          type: string
          description: The parent, or the proposing partner.
        target_organization_id:
          type: string
        state:
          type: string
          enum:
            - proposed
            - active
            - declined
            - ended
        note:
          type: string
        created_by:
          type: object
        decided_by_id:
          type: string
        created_at:
          type: string
          format: date-time
        decided_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
    ProjectRoleAssignment:
      type: object
      required:
        - id
        - project_id
        - role_id
        - user_id
        - created_at
      properties:
        id:
          type: string
        project_id:
          type: string
        role_id:
          type: string
        user_id:
          type: string
        project_grant_id:
          type: string
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    WorkflowDefinition:
      type: object
      description: >-
        Lifecycle workflow definition, schema_version 1. The authoritative schema is api/workflows/definition.v1.json
        (bounded step vocabulary: wait, approval, assign_role, add_to_group, remove_access, notify, call_webhook,
        suspend_user, end).
      required:
        - schema_version
        - triggers
        - steps
      properties:
        schema_version:
          type: integer
          enum:
            - 1
        triggers:
          type: array
          minItems: 1
          maxItems: 5
          items:
            type: object
        steps:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: object
        retry:
          type: object
          properties:
            max_attempts:
              type: integer
              minimum: 1
              maximum: 10
            backoff:
              type: string
    WorkflowCreate:
      type: object
      additionalProperties: false
      required:
        - name
        - definition
      properties:
        name:
          type: string
          maxLength: 100
        description:
          type: string
          maxLength: 500
        definition:
          $ref: '#/components/schemas/WorkflowDefinition'
        note:
          type: string
          maxLength: 500
        requires_approval:
          type: boolean
          description: >-
            Require a second administrator's approval of each revision; forced on by the realm policy
            extensions.workflow_publish_approval.
        owner_user_id:
          type: string
          description: Accountable owner (DOM-009); defaults to the creating user.
    Workflow:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        state:
          type: string
          enum:
            - draft
            - active
            - disabled
        active_revision:
          type: integer
        published_by_id:
          type: string
          description: 'Publisher of the active revision: accountable actor of every run.'
        requires_approval:
          type: boolean
        owner_user_id:
          type: string
        plugin_id:
          type: string
          description: Set when a plugin manages the workflow.
        event_types:
          type: array
          items:
            type: string
        next_fire_at:
          type: string
          format: date-time
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - state
        - requires_approval
        - event_types
        - version
        - created_at
        - updated_at
    WorkflowRevision:
      type: object
      properties:
        id:
          type: string
        workflow_id:
          type: string
        number:
          type: integer
        schema_version:
          type: integer
        definition:
          $ref: '#/components/schemas/WorkflowDefinition'
        definition_hash:
          type: string
        status:
          type: string
          enum:
            - draft
            - approved
            - published
            - superseded
            - rejected
        author_id:
          type: string
        approved_by_id:
          type: string
        approved_at:
          type: string
          format: date-time
        published_by_id:
          type: string
        published_at:
          type: string
          format: date-time
        note:
          type: string
        created_at:
          type: string
          format: date-time
      required:
        - id
        - workflow_id
        - number
        - schema_version
        - definition
        - definition_hash
        - status
        - author_id
        - created_at
    WorkflowRunStart:
      type: object
      additionalProperties: false
      required:
        - subject_id
      properties:
        subject_id:
          type: string
        organization_id:
          type: string
          description: Organization for organization-scoped steps.
    WorkflowStepAttempt:
      type: object
      description: One attempt of one step (EXT-016).
      properties:
        id:
          type: string
        step_index:
          type: integer
        step_id:
          type: string
        step_type:
          type: string
        attempt:
          type: integer
        idempotency_key:
          type: string
          description: Stable for every attempt of the step; sent to endpoints as Idempotency-Key.
        state:
          type: string
          enum:
            - started
            - succeeded
            - failed
        input:
          type: object
        input_version:
          type: string
          description: Revision, definition hash and trigger contract version the attempt ran with.
        result:
          type: object
        error_category:
          type: string
        error:
          type: string
        max_attempts:
          type: integer
        backoff_ms:
          type: integer
        compensation:
          type: string
          enum:
            - none
            - undo
            - notify_endpoint
            - impossible
        compensation_state:
          type: string
          enum:
            - pending
            - done
            - not_needed
            - impossible
            - failed
        compensation_attempts:
          type: integer
        compensation_result:
          type: object
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        compensated_at:
          type: string
          format: date-time
      required:
        - id
        - step_index
        - step_id
        - step_type
        - attempt
        - idempotency_key
        - state
        - input_version
        - max_attempts
        - backoff_ms
        - compensation
        - started_at
    WorkflowApproval:
      type: object
      properties:
        id:
          type: string
        run_id:
          type: string
        workflow_id:
          type: string
        step_index:
          type: integer
        subject_id:
          type: string
        approver_ids:
          type: array
          items:
            type: string
        state:
          type: string
          enum:
            - pending
            - approved
            - rejected
            - expired
            - cancelled
        decided_by_id:
          type: string
        decided_at:
          type: string
          format: date-time
        comment:
          type: string
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
        - id
        - run_id
        - workflow_id
        - step_index
        - subject_id
        - approver_ids
        - state
        - expires_at
        - created_at
    WorkflowRun:
      type: object
      properties:
        id:
          type: string
        workflow_id:
          type: string
        organization_id:
          type: string
        revision:
          type: integer
        definition_hash:
          type: string
        schema_version:
          type: integer
        trigger_type:
          type: string
          enum:
            - event
            - schedule
            - manual
        trigger_event_type:
          type: string
        subject_type:
          type: string
        subject_id:
          type: string
        input:
          type: object
          description: Identifiers-only snapshot of the trigger.
        input_version:
          type: integer
        accountable_id:
          type: string
          description: Publisher of the revision; the audit actor of every effect.
        started_by_id:
          type: string
        depth:
          type: integer
        state:
          type: string
          enum:
            - pending
            - running
            - waiting
            - awaiting_approval
            - compensating
            - succeeded
            - failed
            - compensated
            - compensation_failed
            - cancelled
        step_index:
          type: integer
        context:
          type: object
        next_run_at:
          type: string
          format: date-time
        cancel_requested:
          type: boolean
        error_category:
          type: string
        last_error:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        attempts:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStepAttempt'
        approvals:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowApproval'
      required:
        - id
        - workflow_id
        - revision
        - trigger_type
        - subject_id
        - state
        - accountable_id
        - created_at
    WorkflowDiagnostics:
      type: object
      properties:
        health:
          type: string
          enum:
            - unknown
            - healthy
            - degraded
            - attention_required
        runs_by_state:
          type: object
          additionalProperties:
            type: integer
        step_failures_by_category:
          type: object
          additionalProperties:
            type: integer
        recent_attempts:
          type: integer
        recent_failed_attempts:
          type: integer
        run_duration_p50_ms:
          type: integer
        run_duration_p95_ms:
          type: integer
        pending_approvals:
          type: integer
        oldest_due_seconds:
          type: integer
        compensation_failures:
          type: integer
    PluginPackage:
      type: object
      additionalProperties: false
      required:
        - manifest
        - payload
        - signature
      description: See api/plugins/package.v1.json and manifest.v1.json.
      properties:
        manifest:
          type: string
          description: base64 of the exact manifest bytes (at most 16 KiB).
        payload:
          type: string
          description: >-
            base64 of the exact payload bytes (at most 160 KiB): {hooks: [HookInput], webhooks: [WebhookInput],
            workflows: [{name, description, definition}]}.
        signature:
          type: object
          additionalProperties: false
          required:
            - key_id
            - algorithm
            - value
          properties:
            key_id:
              type: string
            algorithm:
              type: string
              enum:
                - Ed25519
            value:
              type: string
              description: base64 Ed25519 signature over "proudauth-plugin-v1\n" + manifest bytes.
    PluginPartRef:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        state:
          type: string
      required:
        - id
        - name
        - state
    Plugin:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        publisher:
          type: string
        state:
          type: string
          enum:
            - inactive
            - enabled
            - disabled
        installed_version:
          type: string
        previous_version:
          type: string
          description: Target of POST /plugins/{id}/rollback.
        installed_by_id:
          type: string
        installed_at:
          type: string
          format: date-time
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        parts:
          type: object
          properties:
            hooks:
              type: array
              items:
                $ref: '#/components/schemas/PluginPartRef'
            webhooks:
              type: array
              items:
                $ref: '#/components/schemas/PluginPartRef'
            workflows:
              type: array
              items:
                $ref: '#/components/schemas/PluginPartRef'
      required:
        - id
        - name
        - publisher
        - state
        - version
        - created_at
        - updated_at
    PluginVersion:
      type: object
      properties:
        id:
          type: string
        plugin_id:
          type: string
        version:
          type: string
        manifest_version:
          type: integer
        manifest:
          type: object
          description: The signed manifest (api/plugins/manifest.v1.json).
        payload:
          type: object
          description: Returned by GET .../versions/{version} only, for review.
        package_digest:
          type: string
        signing_key_id:
          type: string
        permissions:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
            - pending_review
            - approved
            - rejected
            - installed
            - superseded
        uploaded_by_id:
          type: string
        reviewed_by_id:
          type: string
        reviewed_at:
          type: string
          format: date-time
        review_note:
          type: string
        installed_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
        - id
        - plugin_id
        - version
        - manifest_version
        - manifest
        - package_digest
        - signing_key_id
        - permissions
        - status
        - uploaded_by_id
        - created_at
    PluginInstallResult:
      type: object
      properties:
        plugin:
          $ref: '#/components/schemas/Plugin'
        signing_secrets:
          type: array
          description: Signing secrets of parts this installation created, shown once.
          items:
            type: object
            properties:
              kind:
                type: string
                enum:
                  - hook
                  - webhook
              part_id:
                type: string
              name:
                type: string
              secret:
                type: string
                x-secret: true
      required:
        - plugin
        - signing_secrets
    ExtensionContract:
      type: object
      properties:
        name:
          type: string
          enum:
            - webhook_events
            - hook_contract
            - plugin_manifest
            - workflow_definition
            - management_api
        description:
          type: string
        versions:
          type: array
          items:
            type: object
            properties:
              version:
                type: integer
              status:
                type: string
                enum:
                  - current
                  - supported
                  - deprecated
              sunset:
                type: string
                description: Earliest removal date (YYYY-MM-DD).
              default:
                type: boolean
            required:
              - version
              - status
      required:
        - name
        - versions
    RegistryRule:
      type: object
      additionalProperties: false
      required:
        - repository
      properties:
        repository:
          type: string
          description: Repository name or path.Match pattern (acme/* matches acme/app, not acme/team/app).
        organization_id:
          type: string
          description: Evaluate permissions in this organization; credentials bound to another organization get nothing.
        pull:
          type: string
          description: Permission required to pull.
        push:
          type: string
        delete:
          type: string
        anonymous_pull:
          type: boolean
    RegistryServiceInput:
      type: object
      additionalProperties: false
      required:
        - rules
      properties:
        service:
          type: string
        audience:
          type: string
        token_ttl_seconds:
          type: integer
          minimum: 60
          maximum: 3600
        rules:
          type: array
          minItems: 1
          maxItems: 200
          items:
            $ref: '#/components/schemas/RegistryRule'
        state:
          type: string
          enum:
            - active
            - disabled
    RegistryService:
      type: object
      required:
        - id
        - service
        - resource_id
        - token_ttl_seconds
        - rules
        - state
        - version
      properties:
        id:
          type: string
        service:
          type: string
        resource_id:
          type: string
        token_ttl_seconds:
          type: integer
        rules:
          type: array
          items:
            $ref: '#/components/schemas/RegistryRule'
        state:
          type: string
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    EntitlementHistory:
      type: object
      required:
        - subject
        - at
        - account_state
        - memberships
        - groups
        - assignments
        - permissions
        - oauth_grants
        - policies_in_force
        - realm_policy_revision
        - completeness
      properties:
        subject:
          type: object
        at:
          type: string
          format: date-time
        account_state:
          type: string
          description: active, suspended, locked, recovery_restricted, deleted, not_created or unknown.
        memberships:
          type: array
          items:
            type: object
        groups:
          type: array
          items:
            type: object
        assignments:
          type: array
          items:
            type: object
            properties:
              assignment_id:
                type: string
              role_id:
                type: string
              role_name:
                type: string
              scope_type:
                type: string
              scope_id:
                type: string
              source:
                type: string
              via:
                type: string
              since:
                type: string
                format: date-time
              expires_at:
                type: string
                format: date-time
              permissions:
                type: array
                items:
                  type: string
              denied_permissions:
                type: array
                items:
                  type: string
              permissions_evidence:
                type: string
                enum:
                  - reconstructed
                  - current_definition
                  - unknown
              evidence:
                type: array
                items:
                  type: string
                description: Audit event IDs.
        permissions:
          type: array
          items:
            type: string
        oauth_grants:
          type: array
          items:
            type: object
        policies_in_force:
          type: array
          items:
            type: object
        realm_policy_revision:
          type: integer
        completeness:
          type: object
          properties:
            evidence_from:
              type: string
              format: date-time
            complete:
              type: boolean
            caveats:
              type: array
              items:
                type: string
    SSFTransmitterInput:
      type: object
      additionalProperties: false
      required:
        - name
        - issuer
      properties:
        name:
          type: string
          maxLength: 100
        issuer:
          type: string
        jwks_uri:
          type: string
        jwks:
          type: object
          description: Public JSON Web Key Set (instead of jwks_uri).
        provider_id:
          type: string
          description: Federation connection whose links map iss_sub subjects.
        allow_email_subjects:
          type: boolean
        actions:
          type: object
          description: >-
            Event type URI -> action. session-revoked: record_only | revoke_sessions | revoke_all; credential-change and
            assurance-level-change: record_only | revoke_sessions; credential-compromise: record_only | revoke_all |
            mark_password_compromised; account-disabled and account-purged: record_only | revoke_all | suspend_user;
            account-enabled and identifier-changed: record_only.
          additionalProperties:
            type: string
            enum:
              - record_only
              - revoke_sessions
              - revoke_all
              - mark_password_compromised
              - suspend_user
        max_event_age_seconds:
          type: integer
          minimum: 60
          maximum: 604800
        state:
          type: string
          enum:
            - active
            - disabled
    SSFTransmitter:
      type: object
      required:
        - id
        - name
        - issuer
        - actions
        - state
        - push_endpoint
        - audience
        - version
      properties:
        id:
          type: string
        name:
          type: string
        issuer:
          type: string
        jwks_uri:
          type: string
        jwks:
          type: object
        provider_id:
          type: string
        allow_email_subjects:
          type: boolean
        actions:
          type: object
          additionalProperties:
            type: string
        max_event_age_seconds:
          type: integer
        state:
          type: string
        push_endpoint:
          type: string
        audience:
          type: string
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SSFPushError:
      type: object
      required:
        - err
        - description
      properties:
        err:
          type: string
        description:
          type: string
    Problem:
      type: object
      description: >-
        RFC 9457 problem details (application/problem+json) used by every custom API. Additional extension members (for
        example obligations or original_status) may be present.
      properties:
        type:
          type: string
          format: uri
          description: https://auth.proudbase.com/problems/{code}
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          enum:
            - invalid_request
            - validation_failed
            - unauthenticated
            - forbidden
            - not_found
            - conflict
            - precondition_failed
            - precondition_required
            - rate_limited
            - unavailable
            - internal_error
            - payload_too_large
            - unsupported_media_type
            - step_up_required
            - recent_authentication_required
            - mfa_required
            - recovery_restricted
            - transaction_invalid
            - transaction_expired
            - invalid_credentials
            - invalid_proof
            - unexpected_step
            - password_policy
            - last_owner
            - grant_ceiling_exceeded
            - impersonation_denied
            - impersonation_restricted
            - feature_disabled
            - invitation_invalid
            - last_sign_in_method
            - idempotency_key_reused
            - account_unavailable
            - sso_required
            - upstream_unavailable
          description: Stable machine-readable error code.
        detail:
          type: string
          description: Client-safe detail; never contains secrets.
        errors:
          type: object
          additionalProperties:
            type: string
          description: Field name -> validation message.
        request_id:
          type: string
          description: Correlation identifier, equal to the X-Request-Id response header.
        obligations:
          type: array
          items:
            $ref: '#/components/schemas/Obligation'
          description: Present on step-up / recent-authentication / MFA problems.
        original_status:
          type: integer
          description: Present when an idempotent replay is refused because the original response carried a one-time secret.
      required:
        - type
        - title
        - status
        - code
      additionalProperties: true
    ProfilePatch:
      additionalProperties: false
      properties:
        display_name:
          type:
            - string
            - 'null'
        family_name:
          type:
            - string
            - 'null'
        given_name:
          type:
            - string
            - 'null'
        locale:
          type:
            - string
            - 'null'
        profile:
          additionalProperties: {}
          type:
            - object
            - 'null'
        zoneinfo:
          type:
            - string
            - 'null'
      type: object
    Project:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        description:
          type: string
        environment:
          type: string
        id:
          type: string
        name:
          type: string
        owner_organization_id:
          type: string
        owner_user_id:
          type: string
        realm_id:
          type: string
        state:
          type: string
          enum:
            - active
            - suspended
            - archived
        version:
          format: int64
          type: integer
      type: object
    PushedAuthorizationResponse:
      additionalProperties: false
      properties:
        expires_in:
          type: integer
        request_uri:
          type: string
      required:
        - expires_in
        - request_uri
      type: object
    RealmImpersonationPolicy:
      additionalProperties: false
      properties:
        allow_customer_opt_out:
          type: boolean
        approval:
          type: string
          enum:
            - none
            - second_operator
            - organization_owner
            - customer
        enabled:
          type: boolean
        max_ttl_seconds:
          type: integer
          minimum: 0
          maximum: 300
        notify_customer:
          type: boolean
        require_ticket:
          type: boolean
      type: object
    RealmInteractionPolicy:
      additionalProperties: false
      properties:
        login_ui_url:
          type: string
      type: object
    RealmLifecyclePolicy:
      additionalProperties: false
      properties:
        dormant_days:
          type: integer
          minimum: 0
          maximum: 3650
          description: Accounts without a sign-in for this many days are dormant (0 disables the rule).
        dormant_action:
          type: string
          enum:
            - report
            - suspend
          description: 'report (default): flag once and audit user.dormant_detected; suspend: suspend the account.'
        guest_ttl_days:
          type: integer
          minimum: 0
          maximum: 3650
          description: Guest accounts unused for this many days are deleted (default 30).
        unverified_account_ttl_hours:
          type: integer
      type: object
    RealmLoginPolicy:
      additionalProperties: false
      properties:
        email_otp:
          type: boolean
        identifiers:
          items:
            type: string
          type:
            - array
            - 'null'
        magic_link:
          type: boolean
        passkeys:
          type: boolean
        password:
          type: boolean
        remember_devices:
          type: boolean
        sms_otp:
          type: boolean
        certificates:
          type: boolean
          description: >-
            PROV-016: offer X.509 sign-in (action certificate) with certificates chaining to a user trust anchor and
            bound to the account.
      type: object
    RealmMFAPolicy:
      additionalProperties: false
      properties:
        admin_phishing_resistant:
          type: boolean
        allowed_factors:
          items:
            type: string
            enum:
              - totp
              - hotp
              - webauthn
              - recovery_code
              - email_otp
              - sms_otp
          type:
            - array
            - 'null'
        org_admin_mfa_optional:
          type: boolean
        hotp:
          type: object
          additionalProperties: false
          description: Counter-based codes (MFA-013), offered only when hotp is listed in allowed_factors.
          properties:
            look_ahead:
              type: integer
              minimum: 0
              maximum: 50
            resync_window:
              type: integer
              minimum: 0
              maximum: 1000
        requirement:
          type: string
          enum:
            - optional
            - required
      type: object
    RealmNotificationPolicy:
      additionalProperties: false
      properties:
        new_login_alerts:
          type: boolean
      type: object
    RealmPasswordPolicy:
      additionalProperties: false
      properties:
        history_count:
          type: integer
        min_length:
          type: integer
          description: 0 keeps the operator default; otherwise at least 8.
        revoke_sessions_on_change:
          type: boolean
      type: object
    RealmPolicy:
      additionalProperties: false
      properties:
        audit:
          type: object
          additionalProperties: false
          description: Audit retention scoped to the realm (AUD-009).
          properties:
            retention_days:
              type: integer
              minimum: 30
              maximum: 3650
              description: >-
                Keeps the realm's evidence at least this many days; never shorter than the deployment's
                privacy.audit_retention.
        recovery:
          type: object
          additionalProperties: false
          description: >-
            Assisted recovery controls (MFA-009): with a cooling-off period or required approval, recovery requests are
            scheduled, announced to the owner at once and can be cancelled by the owner.
          properties:
            cooling_off_hours:
              type: integer
              minimum: 0
              maximum: 168
            require_approval:
              type: boolean
        data_access:
          type: object
          additionalProperties: false
          description: >-
            Evidence of identity data reads (USR-018, AUD-015): when log_identity_reads is on, every administrative or
            support read of an account record (user.read) and every account search (user.search) is audited in the
            data_access category with the actor, the account and whether the view was masked; the data itself is never
            logged. The audit record is written before the data is returned.
          properties:
            log_identity_reads:
              type: boolean
            sample_allowed_decisions_percent:
              type: integer
              minimum: 0
              maximum: 100
              description: >-
                Share of ordinary allowed authorization decisions audited, marked sampled (AZ-020). Denials, privileged
                and support decisions are always audited.
        impersonation:
          $ref: '#/components/schemas/RealmImpersonationPolicy'
        interaction:
          $ref: '#/components/schemas/RealmInteractionPolicy'
        lifecycle:
          $ref: '#/components/schemas/RealmLifecyclePolicy'
        login:
          $ref: '#/components/schemas/RealmLoginPolicy'
        mfa:
          $ref: '#/components/schemas/RealmMFAPolicy'
        notifications:
          $ref: '#/components/schemas/RealmNotificationPolicy'
        password:
          $ref: '#/components/schemas/RealmPasswordPolicy'
        profile:
          $ref: '#/components/schemas/RealmProfilePolicy'
        registration:
          $ref: '#/components/schemas/RealmRegistrationPolicy'
        sessions:
          $ref: '#/components/schemas/RealmSessionPolicy'
        webauthn:
          $ref: '#/components/schemas/RealmWebAuthnPolicy'
        domains:
          type: object
          additionalProperties: false
          description: >-
            Periodic re-verification of organization domains (TEN-009): the accepted DNS proof is re-checked every
            recheck_days (default 30); after lapse_after_failures consecutive daily failures (default 3) the
            verification lapses.
          properties:
            recheck_days:
              type: integer
              minimum: 1
              maximum: 365
            lapse_after_failures:
              type: integer
              minimum: 1
              maximum: 30
        policy_engine:
          type: object
          additionalProperties: false
          description: >-
            External policy engine (AZ-026) named from the operator's security.policy_engines; restrict (default) lets
            it only deny, decide makes its answer final (published policies and hooks still restrict it); on_error deny
            (default) or local.
          properties:
            name:
              type: string
            mode:
              type: string
              enum:
                - restrict
                - decide
            on_error:
              type: string
              enum:
                - deny
                - local
        client_registration:
          type: object
          additionalProperties: false
          description: >-
            Dynamic client registration (APP-016, ADV-003), off by default: registrations need an initial access token
            unless open is set; registrations without a token are always held for approval.
          properties:
            enabled:
              type: boolean
            open:
              type: boolean
            require_approval:
              type: boolean
            open_scopes:
              type: array
              items:
                type: string
                enum:
                  - openid
                  - profile
                  - email
                  - phone
                  - address
        authentication_flow:
          type: object
          additionalProperties: false
          description: >-
            Authentication policy (AUT-012, AUT-014, SEC-014): an ordered list of at most 50 rules evaluated once the
            account is known. The first rule whose conditions all hold decides; with no match the sign-in continues
            under the other policies. A rule whose condition needs an unavailable signal (no or a failing
            authentication.risk hook, no client address) applies a restrictive outcome unless on_missing_signal is skip,
            and an allow rule never matches on a missing signal. Each decision is audited as
            authentication.flow.evaluated with the rule, policy revision, signals and missing signals; review outcomes
            raise the authentication_review security signal.
          properties:
            challenge_provider:
              type: string
              description: >-
                Name of an operator-configured challenge provider (security.challenge_providers) offered for challenge
                outcomes.
            email_code_alternative:
              type: boolean
              default: true
              description: Offer a code sent to the verified email as the accessible alternative to the provider challenge.
            rules:
              type: array
              maxItems: 50
              items:
                type: object
                additionalProperties: false
                required:
                  - name
                  - outcome
                properties:
                  name:
                    type: string
                    minLength: 1
                    maxLength: 100
                  outcome:
                    type: string
                    enum:
                      - allow
                      - require_mfa
                      - require_phishing_resistant
                      - challenge
                      - review
                      - deny
                  on_missing_signal:
                    type: string
                    enum:
                      - apply
                      - skip
                    default: apply
                  when:
                    type: object
                    additionalProperties: false
                    description: Conditions that must all hold; omitted members are not checked.
                    properties:
                      clients:
                        type: array
                        maxItems: 50
                        items:
                          type: string
                        description: OAuth client_id values.
                      organizations:
                        type: array
                        maxItems: 50
                        items:
                          type: string
                        description: Organization IDs of the sign-in context.
                      methods:
                        type: array
                        maxItems: 50
                        items:
                          type: string
                          enum:
                            - password
                            - passkey
                            - email_otp
                            - magic_link
                            - sms_otp
                            - sso
                            - certificate
                        description: Primary method used (realm.FlowMethods; certificate is X.509 sign-in, PROV-016).
                      resources:
                        type: array
                        maxItems: 50
                        items:
                          type: string
                        description: Requested resource audiences (any).
                      networks:
                        type: array
                        maxItems: 50
                        items:
                          type: string
                        description: CIDR prefixes containing the client address.
                      outside_networks:
                        type: array
                        maxItems: 50
                        items:
                          type: string
                        description: CIDR prefixes the client address must be outside of.
                      new_device:
                        type: boolean
                        description: True matches a device not remembered for the account.
                      failed_attempts_at_least:
                        type: integer
                        minimum: 0
                        maximum: 1000
                        description: Failed sign-in attempts on the account in the last hour.
                      risk_at_least:
                        type: string
                        enum:
                          - low
                          - medium
                          - high
                        description: Highest level reported by authentication.risk hooks.
                      privileged:
                        type: boolean
                        description: Protected account or holder of a privileged realm role.
                      assurance_below:
                        type: string
                        enum:
                          - urn:proudauth:acr:mfa
                          - urn:proudauth:acr:phishing_resistant
                        description: The factors completed so far give a lower assurance.
        machine:
          type: object
          additionalProperties: false
          description: >-
            Service principals whose accountable owner is suspended, locked or deleted (MCH-007): flag (default) reports
            the departure once and lists it in the credential inventory; disable disables the principal and revokes its
            credentials after owner_departure_grace_days.
          properties:
            owner_departure:
              type: string
              enum:
                - flag
                - disable
            owner_departure_grace_days:
              type: integer
              minimum: 0
              maximum: 90
        tokens:
          type: object
          additionalProperties: false
          description: >-
            Realm limits on access-token lifetimes (TOK-018). Resources and clients set lifetimes; each limit here only
            shortens them: for every access token, for service principals, for user sessions below MFA, and for support
            (impersonation) tokens. The operator maximum always applies.
          properties:
            access_token_ttl_seconds:
              type: integer
              minimum: 30
              maximum: 86400
            service_access_token_ttl_seconds:
              type: integer
              minimum: 30
              maximum: 86400
            single_factor_access_token_ttl_seconds:
              type: integer
              minimum: 30
              maximum: 86400
            impersonation_access_token_ttl_seconds:
              type: integer
              minimum: 30
              maximum: 86400
      type: object
    RealmProfilePolicy:
      additionalProperties: false
      description: >-
        Custom profile attribute schema (USR-007). Self-service and complete_profile may write only user-editable,
        locally sourced attributes defined here; undefined attributes are rejected.
      properties:
        attributes:
          type: array
          maxItems: 50
          items:
            type: object
            additionalProperties: false
            properties:
              name:
                type: string
                pattern: ^[a-z][a-z0-9_]{0,63}$
              type:
                type: string
                enum:
                  - string
                  - number
                  - boolean
                  - enum
              max_length:
                type: integer
                minimum: 0
                maximum: 4096
              enum:
                type: array
                maxItems: 100
                items:
                  type: string
              pattern:
                type: string
                maxLength: 200
              required:
                type: boolean
              user_editable:
                type: boolean
              visibility:
                type: string
                enum:
                  - self
                  - admin
                  - internal
              source:
                type: string
                enum:
                  - local
                  - federation
                  - directory
              claimable:
                type: boolean
            required:
              - name
      type: object
    RealmRegistrationPolicy:
      additionalProperties: false
      properties:
        require_approval:
          type: boolean
          description: Queue self-registrations for review (REG-008); invited registrations are not queued.
        allow_guests:
          type: boolean
        allow_organization_creation:
          type: boolean
        allowed_domains:
          items:
            type: string
          type:
            - array
            - 'null'
        mode:
          type: string
          enum:
            - public
            - closed
            - invitation_only
            - domain_restricted
        require_email_verification:
          type: boolean
        required_profile_fields:
          items:
            type: string
          type:
            - array
            - 'null'
        terms_version:
          type: string
      type: object
    RealmSessionPolicy:
      additionalProperties: false
      properties:
        absolute_seconds:
          type: integer
        idle_seconds:
          type: integer
        max_concurrent:
          type: integer
      type: object
    RealmSettings:
      type: object
      properties:
        realm:
          type: string
        issuer:
          type: string
          format: uri
        state:
          type: string
        policy:
          $ref: '#/components/schemas/RealmPolicy'
        policy_revision:
          type: integer
          format: int64
        version:
          type: integer
          format: int64
      required:
        - realm
        - issuer
        - state
        - policy
        - policy_revision
        - version
    RealmWebAuthnPolicy:
      additionalProperties: false
      properties:
        allow_synced:
          type: boolean
        origins:
          items:
            type: string
          type:
            - array
            - 'null'
        rp_id:
          type: string
        rp_name:
          type: string
        user_verification:
          type: string
      type: object
    RegistrationInput:
      additionalProperties: false
      properties:
        display_name:
          type: string
        email:
          type: string
        family_name:
          type: string
        given_name:
          type: string
        invitation:
          type: string
          x-secret: true
          description: Invitation secret to accept during registration.
        locale:
          type: string
        organization:
          oneOf:
            - $ref: '#/components/schemas/OrganizationInput'
            - type: 'null'
        password:
          type: string
          format: password
        profile:
          additionalProperties: {}
          type:
            - object
            - 'null'
        terms_version:
          type: string
        username:
          type: string
      type: object
    Resource:
      additionalProperties: false
      properties:
        access_token_ttl_seconds:
          type: integer
        audience:
          type: string
        created_at:
          format: date-time
          type: string
        description:
          type: string
        id:
          type: string
        impersonation_enabled:
          type: boolean
        impersonation_policy:
          $ref: '#/components/schemas/ApplicationImpersonationPolicy'
        kind:
          type: string
        name:
          type: string
        project_id:
          type: string
        realm_id:
          type: string
        requires_organization:
          type: boolean
        scopes:
          items:
            $ref: '#/components/schemas/ApplicationScope'
          type:
            - array
            - 'null'
        signing_algorithm:
          type: string
        state:
          type: string
        token_format:
          type: string
        verification_mode:
          type: string
        version:
          format: int64
          type: integer
      required:
        - access_token_ttl_seconds
        - audience
        - created_at
        - id
        - impersonation_enabled
        - impersonation_policy
        - kind
        - name
        - realm_id
        - requires_organization
        - signing_algorithm
        - state
        - token_format
        - verification_mode
        - version
      type: object
    ResourceGrant:
      additionalProperties: false
      properties:
        allowed_scopes:
          items:
            type: string
          type:
            - array
            - 'null'
        client_ref:
          type: string
        exchange_policy:
          $ref: '#/components/schemas/ExchangePolicy'
        id:
          type: string
        resource_id:
          type: string
        subject_types:
          items:
            type: string
          type:
            - array
            - 'null'
      required:
        - allowed_scopes
        - client_ref
        - exchange_policy
        - id
        - resource_id
        - subject_types
      type: object
    ResourceInput:
      additionalProperties: false
      properties:
        signing_algorithm:
          type: string
          description: >-
            Pins the access-token JWS algorithm (TOK-005). Must be in security.allowed_algorithms; symmetric algorithms
            and none are rejected. Issuance fails closed if the realm's active key uses another algorithm, and key
            rotation to another algorithm is refused while resources pin this one. Defaults to keys.signing_algorithm.
        access_token_ttl_seconds:
          type: integer
        audience:
          type: string
        description:
          type: string
        impersonation_enabled:
          type: boolean
        impersonation_policy:
          $ref: '#/components/schemas/ApplicationImpersonationPolicy'
        name:
          type: string
        project_id:
          type: string
        requires_organization:
          type:
            - boolean
            - 'null'
        scopes:
          items:
            $ref: '#/components/schemas/ScopeInput'
          type:
            - array
            - 'null'
        token_format:
          type: string
          enum:
            - jwt
            - opaque
        verification_mode:
          type: string
          enum:
            - offline
            - bounded_online
            - strict_online
      type: object
      required:
        - audience
        - name
    RevokedSessions:
      type: object
      properties:
        revoked_sessions:
          type: integer
      required:
        - revoked_sessions
    Role:
      additionalProperties: false
      properties:
        boundary_type:
          type: string
        built_in:
          type: boolean
        composite_role_ids:
          items:
            type: string
          type:
            - array
            - 'null'
        created_at:
          format: date-time
          type: string
        denied_permissions:
          items:
            type: string
          type:
            - array
            - 'null'
        description:
          type: string
        id:
          type: string
        incompatible_role_ids:
          items:
            type: string
          type:
            - array
            - 'null'
        is_owner_role:
          type: boolean
        name:
          type: string
        organization_id:
          type: string
        permissions:
          items:
            type: string
          type:
            - array
            - 'null'
        project_id:
          type: string
        protected:
          type: boolean
        realm_id:
          type: string
        requires_approval:
          type: boolean
        version:
          format: int64
          type: integer
      required:
        - boundary_type
        - built_in
        - composite_role_ids
        - created_at
        - id
        - incompatible_role_ids
        - is_owner_role
        - name
        - permissions
        - protected
        - realm_id
        - requires_approval
        - version
      type: object
    RoleAssignment:
      additionalProperties: false
      properties:
        approved_by:
          type: string
        conditions:
          additionalProperties: {}
          type:
            - object
            - 'null'
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          type:
            - string
            - 'null'
        granted_by:
          type: string
        id:
          type: string
        membership_id:
          type: string
        reason:
          type: string
        role_id:
          type: string
        role_name:
          type: string
        scope:
          $ref: '#/components/schemas/AuthzScope'
        source:
          type: string
        subject:
          $ref: '#/components/schemas/AuthzSubject'
        valid_from:
          format: date-time
          type:
            - string
            - 'null'
      required:
        - created_at
        - id
        - role_id
        - scope
        - source
        - subject
      type: object
    RoleInput:
      additionalProperties: false
      properties:
        boundary_type:
          type: string
          enum:
            - realm
            - organization
            - project
        composite_role_ids:
          items:
            type: string
          type:
            - array
            - 'null'
        denied_permissions:
          items:
            type: string
          type:
            - array
            - 'null'
        description:
          type: string
        incompatible_role_ids:
          items:
            type: string
          type:
            - array
            - 'null'
        name:
          type: string
        organization_id:
          type: string
        permissions:
          items:
            type: string
          type:
            - array
            - 'null'
        project_id:
          type: string
        requires_approval:
          type: boolean
      type: object
      required:
        - name
    ScopeInput:
      additionalProperties: false
      properties:
        required_permissions:
          type: array
          maxItems: 10
          items:
            type: string
          description: >-
            Subject policy (TOK-008); the scope is issued only to subjects holding all of these permissions in the
            token's organization or realm context, re-checked on refresh.
        consent_text:
          type: string
        description:
          type: string
        is_default:
          type: boolean
          description: >-
            Default grant (APP-007): a token or authorization request that names this scope's resource but none of its
            scopes is requested with the resource's default scopes, as far as the client's resource grant lists them.
            They then pass the checks of a requested scope (consent, step-up, the organization's scope ceiling,
            required_permissions), so a default scope is never issued where a requested one would not be. A request
            naming any scope of the resource gets no defaults, and a refresh never adds defaults declared after the
            authorization.
        name:
          type: string
        sensitivity:
          type: string
          description: Defaults to normal. privileged scopes require MFA (step-up) even without step_up_acr.
        step_up_acr:
          type: string
          enum:
            - urn:proudauth:acr:mfa
            - urn:proudauth:acr:phishing_resistant
          description: >-
            Step-up policy (AUT-010): a request for the scope makes this assurance a requirement of the transaction; an
            SSO session below it is stepped up, never downgraded.
        max_auth_age_seconds:
          type: integer
          minimum: 60
          maximum: 86400
          description: >-
            The session's authentication must be at most this old when the scope is requested; refresh drops the scope
            once the grant's authentication is older.
      type: object
      required:
        - name
    SecurityEvent:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        occurred_at:
          type: string
          format: date-time
        outcome:
          type: string
        network:
          type: string
        actor_type:
          type: string
          description: Present when another party (support or an administrator) acted on the account.
        support_grant_id:
          type: string
      required:
        - id
        - type
        - occurred_at
        - outcome
        - network
    SelfCredential:
      description: Safe authenticator metadata. Verifiers, seeds and public keys are never returned.
      oneOf:
        - type: object
          title: Credential
          properties:
            id:
              type: string
            type:
              type: string
            name:
              type: string
            state:
              type: string
              enum:
                - active
                - compromised
            created_at:
              type: string
              format: date-time
            last_used_at:
              type:
                - string
                - 'null'
              format: date-time
          required:
            - id
            - type
            - name
            - state
            - created_at
            - last_used_at
        - type: object
          title: Passkey
          properties:
            id:
              type: string
            type:
              type: string
              const: webauthn
            name:
              type: string
            synced:
              type: boolean
            backup_eligible:
              type: boolean
            user_verifying:
              type: boolean
            created_at:
              type: string
              format: date-time
            last_used_at:
              type:
                - string
                - 'null'
              format: date-time
          required:
            - id
            - type
            - name
            - synced
            - backup_eligible
            - user_verifying
            - created_at
            - last_used_at
    SelfSession:
      type: object
      properties:
        id:
          type: string
        current:
          type: boolean
        created_at:
          type: string
          format: date-time
        last_activity_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        amr:
          type:
            - array
            - 'null'
          items:
            type: string
        acr:
          type: string
        user_agent:
          type: string
        remember_me:
          type: boolean
        recovery_restricted:
          type: boolean
        device:
          type: string
          description: Display hint derived from the user agent (SES-013); never a security signal.
        network:
          type: string
          description: Privacy-reduced network (/24 or /48) the session started from.
      required:
        - id
        - current
        - created_at
        - last_activity_at
        - expires_at
        - amr
        - acr
        - user_agent
        - remember_me
        - recovery_restricted
    SelfUser:
      type: object
      description: Self-service view of the calling user.
      properties:
        id:
          type: string
        state:
          type: string
          enum:
            - pending_verification
            - active
            - suspended
            - locked
            - recovery_restricted
            - pending_deletion
            - deleted
        display_name:
          type: string
        given_name:
          type: string
        family_name:
          type: string
        locale:
          type: string
        zoneinfo:
          type: string
        profile:
          type:
            - object
            - 'null'
          additionalProperties: true
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/UserIdentifier'
        required_actions:
          type:
            - array
            - 'null'
          items:
            type: string
            enum:
              - update_password
              - verify_email
              - configure_totp
              - accept_terms
              - complete_profile
              - verify_contact
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        version:
          type: integer
          format: int64
        deletion_scheduled_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - state
        - display_name
        - given_name
        - family_name
        - locale
        - zoneinfo
        - profile
        - identifiers
        - required_actions
        - created_at
        - updated_at
        - version
        - deletion_scheduled_at
    ServicePrincipal:
      additionalProperties: false
      properties:
        allowed_organization_ids:
          items:
            type: string
          type:
            - array
            - 'null'
        created_at:
          format: date-time
          type: string
        description:
          type: string
        id:
          type: string
        is_agent:
          type: boolean
          description: >-
            An autonomous agent (MCH-017): needs an accountable human owner (owner_user_id; 422 otherwise), privileged
            roles reach it only through two-party approval, and its tokens carry agent=true (and act.agent=true when it
            acts for a person). Agents pass through ordinary authorization like any service.
        name:
          type: string
        owner_organization_id:
          type: string
        owner_user_id:
          type: string
        permission_revision:
          format: int64
          type: integer
        state:
          type: string
          enum:
            - active
            - disabled
            - deleted
        version:
          format: int64
          type: integer
      required:
        - allowed_organization_ids
        - created_at
        - id
        - is_agent
        - name
        - permission_revision
        - state
        - version
      type: object
    ServicePrincipalInput:
      additionalProperties: false
      properties:
        allowed_organization_ids:
          items:
            type: string
          type:
            - array
            - 'null'
        description:
          type: string
        is_agent:
          type: boolean
          description: >-
            An autonomous agent (MCH-017): needs an accountable human owner (owner_user_id; 422 otherwise), privileged
            roles reach it only through two-party approval, and its tokens carry agent=true (and act.agent=true when it
            acts for a person). Agents pass through ordinary authorization like any service.
        name:
          type: string
          maxLength: 200
        owner_organization_id:
          type: string
        owner_user_id:
          type: string
      type: object
      required:
        - name
    Session:
      additionalProperties: false
      properties:
        absolute_expires_at:
          format: date-time
          type: string
        acr:
          type: string
        amr:
          items:
            type: string
          type:
            - array
            - 'null'
        auth_time:
          format: date-time
          type: string
        created_at:
          format: date-time
          type: string
        device_label:
          type: string
        id:
          type: string
        idle_expires_at:
          format: date-time
          type: string
        last_activity_at:
          format: date-time
          type: string
        mfa_time:
          format: date-time
          type:
            - string
            - 'null'
        network:
          type: string
        realm_id:
          type: string
        recovery_restricted:
          type: boolean
        remember_me:
          type: boolean
        revoke_reason:
          type: string
        revoked_at:
          format: date-time
          type:
            - string
            - 'null'
        state:
          type: string
        transient:
          type: boolean
        user_agent:
          type: string
        user_id:
          type: string
      required:
        - absolute_expires_at
        - acr
        - amr
        - auth_time
        - created_at
        - id
        - idle_expires_at
        - last_activity_at
        - realm_id
        - recovery_restricted
        - remember_me
        - state
        - transient
        - user_id
      type: object
    SigningKeyMetadata:
      additionalProperties: false
      properties:
        activated_at:
          format: date-time
          type:
            - string
            - 'null'
        algorithm:
          type: string
        compromised_at:
          format: date-time
          type:
            - string
            - 'null'
        created_at:
          format: date-time
          type: string
        kid:
          type: string
        publish_until:
          format: date-time
          type:
            - string
            - 'null'
        retiring_at:
          format: date-time
          type:
            - string
            - 'null'
        state:
          type: string
      required:
        - algorithm
        - created_at
        - kid
        - state
      type: object
    StateResponse:
      type: object
      properties:
        state:
          type: string
      required:
        - state
    TOTPEnrollment:
      additionalProperties: false
      properties:
        credential_id:
          type: string
        expires_at:
          format: date-time
          type: string
        otpauth_uri:
          type: string
          x-secret: true
          description: otpauth:// provisioning URI containing the seed. Returned once.
        secret:
          type: string
          x-secret: true
          description: Base32 TOTP seed. Returned once during enrollment.
      required:
        - credential_id
        - expires_at
        - otpauth_uri
        - secret
      type: object
    HOTPEnrollment:
      additionalProperties: false
      properties:
        credential_id:
          type: string
        expires_at:
          format: date-time
          type: string
        counter:
          type: integer
          description: The counter the token starts at (0).
        otpauth_uri:
          type: string
          x-secret: true
          description: otpauth://hotp provisioning URI containing the seed and counter. Returned once.
        secret:
          type: string
          x-secret: true
          description: Base32 HOTP seed. Returned once during enrollment.
      required:
        - counter
        - credential_id
        - expires_at
        - otpauth_uri
        - secret
      type: object
    TokenResponse:
      additionalProperties: false
      properties:
        access_token:
          type: string
          x-secret: true
        expires_in:
          type: integer
        id_token:
          type: string
          x-secret: true
        issued_token_type:
          type: string
        refresh_token:
          type: string
          x-secret: true
        scope:
          type: string
        token_type:
          type: string
          enum:
            - Bearer
            - DPoP
          description: >-
            DPoP for an access token bound to a DPoP key (cnf.jkt, RFC 9449); Bearer for every other token,
            certificate-bound tokens (cnf.x5t#S256, RFC 8705) included. The same for every grant, token exchange
            included.
      required:
        - access_token
        - expires_in
        - token_type
      type: object
    TransactionAction:
      additionalProperties: false
      properties:
        fields:
          items:
            type: string
          type:
            - array
            - 'null'
        options:
          additionalProperties: {}
          type:
            - object
            - 'null'
        required:
          type: boolean
        type:
          type: string
      required:
        - required
        - type
      type: object
    TransactionStarted:
      type: object
      properties:
        transaction_id:
          type: string
        continuation_token:
          type: string
          x-secret: true
          description: >-
            Continuation authority for headless clients; send it in X-Transaction-Token on every later step. Returned
            exactly once; it is never stored in plaintext, never shown again and never replayed from the idempotency
            store.
        device_request:
          type: object
          description: Present only when the transaction was started from a device user code.
          properties:
            client_name:
              type: string
            client_id:
              type: string
            scopes:
              type:
                - array
                - 'null'
              items:
                type: string
            expires_at:
              type: string
              format: date-time
        state:
          $ref: '#/components/schemas/TransactionState'
      required:
        - transaction_id
        - continuation_token
        - state
    TransactionState:
      additionalProperties: false
      properties:
        client:
          additionalProperties: {}
          type:
            - object
            - 'null'
        completed_factors:
          items:
            type: string
          type:
            - array
            - 'null'
        csrf_token:
          type: string
          description: Returned only to browser (cookie-bound) callers from an allowed origin; send it back in X-CSRF-Token.
        error:
          type: string
        expires_at:
          format: date-time
          type: string
        external_redirect:
          type: string
          description: Upstream authorization URL the browser must visit (federated sign-in).
        id:
          type: string
        intent:
          type: string
        locale:
          type: string
        next_actions:
          items:
            $ref: '#/components/schemas/TransactionAction'
          type:
            - array
            - 'null'
        notice:
          type: string
          description: Non-terminal condition to show, e.g. upstream_unavailable.
        one_time:
          additionalProperties: {}
          type:
            - object
            - 'null'
          x-secret: true
          description: Secrets displayed exactly once (for example newly generated recovery codes). Never shown again.
        redirect_to:
          type: string
        status:
          type: string
          enum:
            - pending
            - completed
            - cancelled
            - expired
            - failed
        user:
          additionalProperties: {}
          type:
            - object
            - 'null'
        webauthn:
          description: >-
            WebAuthn ceremony options for the client (PublicKeyCredentialRequestOptions or CreationOptions JSON) when a
            passkey step is pending. Not secret.
      required:
        - client
        - completed_factors
        - expires_at
        - id
        - intent
        - next_actions
        - status
      type: object
    UserIdentifier:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - email
            - phone
            - username
        value:
          type: string
        verified:
          type: boolean
        is_primary:
          type: boolean
      required:
        - id
        - type
        - value
        - verified
        - is_primary
    UserInfo:
      type: object
      additionalProperties: true
      properties:
        sub:
          type: string
      required:
        - sub
      description: Standard OIDC claims permitted by the granted scopes.
    WebhookDelivery:
      additionalProperties: false
      properties:
        attempts:
          type: integer
        created_at:
          format: date-time
          type: string
        delivered_at:
          format: date-time
          type:
            - string
            - 'null'
        event_id:
          type: string
        event_type:
          type: string
        id:
          type: string
        last_response_category:
          type: string
        last_status_code:
          type:
            - integer
            - 'null'
        next_attempt_at:
          format: date-time
          type: string
        state:
          type: string
      required:
        - attempts
        - created_at
        - event_id
        - event_type
        - id
        - next_attempt_at
        - state
      type: object
    WebhookInput:
      additionalProperties: false
      properties:
        allow_private_network:
          type: boolean
        destination_url:
          type: string
          format: uri
          description: HTTPS destination subject to the operator egress policy.
        event_types:
          items:
            type: string
          type:
            - array
            - 'null'
          minItems: 1
          description: Event types from the catalog in api/events (also returned by GET /webhooks as event_types).
        name:
          type: string
        organization_id:
          type: string
        payload_form:
          type: string
          enum:
            - minimal
            - standard
        event_version:
          type: integer
          enum:
            - 1
            - 2
          description: Event schema version deliveries are rendered to (EXT-018); default 1. See api/events/README.md.
      type: object
      required:
        - destination_url
        - event_types
        - name
    WebhookSubscription:
      additionalProperties: false
      properties:
        allow_private_network:
          type: boolean
        created_at:
          format: date-time
          type: string
        destination_url:
          type: string
        event_types:
          items:
            type: string
          type:
            - array
            - 'null'
        id:
          type: string
        name:
          type: string
        organization_id:
          type: string
        owner_user_id:
          type: string
        payload_form:
          type: string
        state:
          type: string
          enum:
            - active
            - paused
            - disabled
        version:
          format: int64
          type: integer
        event_version:
          type: integer
          description: Event schema version of deliveries (EXT-018).
        plugin_id:
          type: string
          description: Set when a plugin manages the subscription; PATCH and DELETE then return 409 (EXT-014).
      required:
        - allow_private_network
        - created_at
        - destination_url
        - event_types
        - id
        - name
        - payload_form
        - state
        - version
        - event_version