openapi.yaml

# OpenAPI 3.0 specification of the Fulla OAuth2/OIDC authorization server.
#
# Governance (2026-08, spec-governance M0):
#   - This file is the SINGLE SOURCE OF TRUTH for the HTTP API contract
#     (client SDK generation, endpoint consistency gate, breaking-change gate).
#   - tools/openapi-governance/check_spec_governance.py (CI static-checks)
#     asserts: METHOD+path set == C++ doc registrations == Drogon routes
#     (modulo documented exclusions), and info.version == cmake/Version.cmake.
#   - .github/workflows/openapi-governance.yml runs `oasdiff breaking` against
#     the base branch; breaking changes require a major bump or an entry in
#     tools/openapi-governance/oasdiff-breaking-ignore.md.
#   - After editing controllers or this file, run:
#       python tools/openapi-governance/check_spec_governance.py
#       python -m openapi_spec_validator apps/server/openapi.yaml
components:
  schemas:
    Error:
      description: >-
        The nested error object of the application error envelope. Application
        (non-OAuth2-protocol) endpoints respond with {"error": {...}} on
        failure; /oauth2/* and /.well-known/* endpoints use RFC 6749 §5.2
        bodies instead (see OAuth2Error).
      properties:
        category:
          type: string
          description: Error category, e.g. VALIDATION / AUTH / AUTHZ / DB / INTERNAL.
        code:
          type: string
          description: Machine-readable error code, e.g. VALIDATION_INVALID_INPUT.
        message:
          type: string
        request_id:
          type: string
        numeric_code:
          type: integer
          description: Numeric catalog code (present iff the code is registered, e.g. 3001).
        details:
          type: string
          description: Extra context; only emitted when the server runs in non-production mode.
      type: object
    ErrorEnvelope:
      description: Application-endpoint error wrapper.
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
      - error
      type: object
    OAuth2Error:
      description: >-
        RFC 6749 §5.2 error body used by /oauth2/* and /.well-known/*
        endpoints (with Cache-Control: no-store). HTTP status per code:
        invalid_request 400, invalid_client 401, invalid_grant 400,
        unauthorized_client 400, unsupported_grant_type 400, invalid_scope 400,
        access_denied 403, authorization_pending 400, slow_down 400,
        expired_token 400, server_error 500, temporarily_unavailable 503.
        Bearer-protected resources (userinfo) additionally use the RFC 6750
        section 3.1 codes invalid_token (401) and insufficient_scope (403).
      properties:
        error:
          type: string
          enum:
          - invalid_request
          - invalid_client
          - invalid_grant
          - unauthorized_client
          - unsupported_grant_type
          - invalid_scope
          - access_denied
          - unsupported_token_type
          - invalid_token
          - insufficient_scope
          - authorization_pending
          - slow_down
          - expired_token
          - server_error
          - temporarily_unavailable
        error_description:
          type: string
        error_uri:
          type: string
      required:
      - error
      type: object
    TokenResponse:
      description: >-
        Token endpoint success body (grant-dependent fields). authorization_code:
        access_token/token_type/expires_in/refresh_token/roles + id_token iff
        scope includes openid (no scope echo). refresh_token: rotated
        refresh_token, no roles. client_credentials: scope echo, NO
        refresh_token. device_code: refresh_token + optional scope/id_token.
        Always carries Cache-Control: no-store / Pragma: no-cache.
      properties:
        access_token:
          type: string
        token_type:
          type: string
          description: Always "Bearer".
        expires_in:
          type: integer
          format: int64
          description: Seconds until access_token expiry.
        refresh_token:
          type: string
          description: Present for grants that issue refresh tokens (rotated on refresh).
        scope:
          type: string
          description: Space-separated scopes; echoed for client_credentials/device grants only.
        roles:
          type: array
          items:
            type: string
          description: Role names; authorization_code grant only.
        id_token:
          type: string
          description: OIDC ID token (JWT); present iff scope includes openid and signing keys are configured.
      required:
      - access_token
      - token_type
      - expires_in
      type: object
    SocialLoginTokenResponse:
      description: >-
        First-party token pair issued by a social login endpoint
        (/api/{github,google,wechat}/login) once the provider identity is
        linked to a local account (or auto-created on first login). Issued
        for the configured first-party client
        (external_auth.social_token_client_id, default fulla-portal) with
        scope "openid profile email". Recorded as a SOCIAL_LOGIN_TOKEN_ISSUED
        audit event (NOT a consent row) — an explicit social-consent
        interaction is a registered follow-up.
      properties:
        access_token:
          type: string
        token_type:
          type: string
          description: Always "Bearer".
        expires_in:
          type: integer
          format: int64
        refresh_token:
          type: string
      required:
      - access_token
      - token_type
      - expires_in
      - refresh_token
      type: object
    WebAuthnRegistrationCredential:
      description: >-
        Browser PublicKeyCredential for navigator.credentials.create()
        (#142). All binary fields are base64url without padding. The server
        ignores any client-submitted public_key: the stored key comes from
        the verified attestation object's COSE bytes.
      properties:
        id:
          type: string
          description: base64url credential id (must equal rawId).
        rawId:
          type: string
        response:
          type: object
          properties:
            attestationObject:
              type: string
              description: base64url CBOR attestation object (fmt "none" only).
            clientDataJSON:
              type: string
          required:
          - attestationObject
          - clientDataJSON
        name:
          type: string
          description: Optional human-readable label (default "Passkey").
      required:
      - id
      - rawId
      - response
      type: object
    WebAuthnAssertionCredential:
      description: >-
        Browser PublicKeyCredential for navigator.credentials.get() (#142).
        All binary fields are base64url without padding.
      properties:
        id:
          type: string
          description: base64url credential id (must equal rawId).
        rawId:
          type: string
        response:
          type: object
          properties:
            authenticatorData:
              type: string
            clientDataJSON:
              type: string
            signature:
              type: string
              description: base64url ASN.1 DER ECDSA signature.
          required:
          - authenticatorData
          - clientDataJSON
          - signature
        userHandle:
          type: string
          description: Optional base64url user handle; when present it must
            name the credential's owner.
      required:
      - id
      - rawId
      - response
      type: object
    IntrospectionResponse:
      description: >-
        RFC 7662 introspection body. Inactive tokens return {"active": false}
        only. Active responses always carry iss (backfilled from config);
        Cache-Control: no-store.
      properties:
        active:
          type: boolean
        client_id:
          type: string
        token_type:
          type: string
          description: Always "Bearer" when active.
        exp:
          type: integer
          format: int64
        iat:
          type: integer
          format: int64
        nbf:
          type: integer
          format: int64
        sub:
          type: string
          description: Resource-owner subject; "client:<id>" for client_credentials tokens.
        aud:
          type: string
        iss:
          type: string
        scope:
          type: string
          description: Space-separated scopes.
        org_id:
          type: integer
          format: int32
          description: 'v1.4.0: present when the token was issued in org context
            (authorize org_id parameter). The token''s own binding; roles/name
            stay userinfo-only.'
      required:
      - active
      type: object
    UserInfoResponse:
      description: >-
        OIDC Core §5.3 userinfo claims, scope-gated per §5.4 (P0-2): profile
        claims (name/preferred_username/picture) require the profile scope;
        email/email_verified require the email scope; sub is unconditional.
        email_verified present iff email present; roles present iff
        non-empty. org_ctx present iff the token was issued in org context,
        carries the org scope, and the user is still a member (v1.4.0;
        membership is re-checked in real time).
      properties:
        sub:
          type: string
          description: Subject (public user id, stringified).
        name:
          type: string
          description: 'display_name when set, else username, else email
            (profile scope).'
        preferred_username:
          type: string
          description: 'Standard OIDC claim name (profile scope); the legacy
            username key dual-emits alongside it until v1.6.0.'
        username:
          type: string
          description: 'Legacy key (deprecated, removed in v1.6.0) — use
            preferred_username (profile scope).'
        picture:
          type: string
          description: Avatar URL (profile scope).
        email:
          type: string
          description: Email address (email scope).
        email_verified:
          type: boolean
          description: Email verification status (email scope).
        roles:
          type: array
          items:
            type: string
        org_ctx:
          type: object
          description: 'v1.4.0: the ACTIVE organization context (id + name + the
            user''s current roles in it); active-org-only, never the full
            membership list.'
          properties:
            org_id:
              type: integer
              format: int32
            org_name:
              type: string
            roles:
              type: array
              items:
                type: string
      required:
      - sub
      - name
      type: object
    OpenIDConfiguration:
      description: OIDC Discovery 1.0 provider metadata.
      properties:
        issuer:
          type: string
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        device_authorization_endpoint:
          type: string
        userinfo_endpoint:
          type: string
        jwks_uri:
          type: string
        introspection_endpoint:
          type: string
        revocation_endpoint:
          type: string
        registration_endpoint:
          type: string
        scopes_supported:
          type: array
          items:
            type: string
        response_types_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
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        code_challenge_methods_supported:
          type: array
          items:
            type: string
        prompt_values_supported:
          type: array
          items:
            type: string
        acr_values_supported:
          type: array
          items:
            type: string
        end_session_endpoint:
          type: string
        backchannel_logout_supported:
          type: boolean
        backchannel_logout_session_supported:
          type: boolean
        claims_supported:
          type: array
          items:
            type: string
      type: object
    OAuthAuthorizationServerMetadata:
      description: RFC 8414 authorization server metadata (no userinfo/jwks entries; OIDC discovery carries those).
      properties:
        issuer:
          type: string
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        device_authorization_endpoint:
          type: string
        introspection_endpoint:
          type: string
        introspection_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        revocation_endpoint:
          type: string
        revocation_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        registration_endpoint:
          type: string
        scopes_supported:
          type: array
          items:
            type: string
        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
        code_challenge_methods_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        service_documentation:
          type: string
        op_policy_uri:
          type: string
        op_tos_uri:
          type: string
      type: object
    JWKSet:
      description: 'RFC 7517 JSON Web Key Set (Cache-Control: public, max-age=3600).'
      properties:
        keys:
          type: array
          items:
            type: object
            properties:
              kty:
                type: string
              kid:
                type: string
              use:
                type: string
              alg:
                type: string
              n:
                type: string
              e:
                type: string
              x5c:
                type: array
                items:
                  type: string
            required:
            - kty
      required:
      - keys
      type: object
    LoginSuccessResponse:
      description: /oauth2/login success when json=true (otherwise a 302 redirect with code+state query).
      properties:
        code:
          type: string
          description: The issued authorization code.
        location:
          type: string
          description: Full redirect URI with code and state query parameters.
      required:
      - code
      - location
      type: object
    MfaRequiredResponse:
      description: /oauth2/login response when the account has MFA enabled; complete the flow at POST /oauth2/mfa/verify.
      properties:
        mfa_required:
          type: boolean
        mfa_token:
          type: string
          description: Pending-MFA token to submit to /oauth2/mfa/verify.
        message:
          type: string
      required:
      - mfa_required
      - mfa_token
      type: object
    PasswordChangeRequiredResponse:
      description: '/oauth2/login response while the account is flagged must_change_password
        (#145: bootstrap admin, admin-created users). No authorization code is
        issued until the password is changed via POST /oauth2/password/change.'
      properties:
        password_change_required:
          type: boolean
        message:
          type: string
      required:
      - password_change_required
      type: object
    MessageResponse:
      properties:
        message:
          type: string
      required:
      - message
      type: object
    SocialLinkEntry:
      description: One social provider identity linked to the current user.
      properties:
        provider:
          type: string
          enum: [github, google, wechat]
        subject:
          type: string
          description: Provider-scoped stable id (GitHub numeric id, Google
            sub, WeChat openid).
        linked_at:
          type: string
          description: Mapping row creation timestamp.
      required:
      - provider
      - subject
      type: object
    SocialLinksList:
      properties:
        social_links:
          type: array
          items:
            $ref: '#/components/schemas/SocialLinkEntry'
        total:
          type: integer
      required:
      - social_links
      - total
      type: object
    SocialLinkResult:
      description: Result of a link/unlink mutation.
      properties:
        provider:
          type: string
          enum: [github, google, wechat]
        subject:
          type: string
          description: Provider subject (link success; unlink success keeps
            the removed subject).
        message:
          type: string
      required:
      - provider
      - message
      type: object
    AuthProvider:
      description: An external login provider currently enabled on this
        deployment (v1.4.0 provider tiers). authorize_url is the fully built
        provider authorize URL — the SPA redirects to it as-is; the redirect
        target resolves from the per-provider redirect_uri override, else
        frontend.url + /callback/{provider}.
      properties:
        authorize_url:
          type: string
        provider:
          type: string
          enum: [github, google, wechat]
      required:
      - provider
      - authorize_url
      type: object
    AuthProvidersResponse:
      description: External login provider discovery. An empty list means
        external login is disabled on this deployment.
      properties:
        providers:
          type: array
          items:
            $ref: '#/components/schemas/AuthProvider'
      required:
      - providers
      type: object
    DeviceAuthorizationResponse:
      description: 'RFC 8628 device authorization response. The verification URIs
        point at the admin console device-approval page by default (admin_console.url
        config + /admin/devices, #146); override with
        custom_config.device_authorization.verification_uri.'
      properties:
        device_code:
          type: string
        user_code:
          type: string
          description: 8 characters from the A-Z2-9 alphabet (no 0/1/I/O).
        verification_uri:
          type: string
          description: Page the user visits to approve the device (admin console
            /admin/devices by default).
        verification_uri_complete:
          type: string
          description: 'verification_uri with ?user_code=<code> appended (RFC 8628
            §3.3.1) so the approval page can prefill the code.'
        expires_in:
          type: integer
          description: Device code lifetime in seconds (600).
        interval:
          type: integer
          description: Required polling interval in seconds (5).
      required:
      - device_code
      - user_code
      - verification_uri
      - expires_in
      - interval
      type: object
    HealthStatus:
      properties:
        status:
          type: string
          enum:
          - ok
          - degraded
          - unhealthy
        service:
          type: string
        timestamp:
          type: integer
          format: int64
        storage_type:
          type: string
        database:
          type: string
          description: connected / disconnected / not_configured / unknown
        redis:
          type: string
          description: connected / disconnected / not_configured
      required:
      - status
      type: object
    Organization:
      properties:
        id:
          type: integer
        slug:
          type: string
        name:
          type: string
        logo_uri:
          type: string
        primary_color:
          type: string
        issuer_override:
          type: string
      type: object
    TokenRequest:
      description: >-
        RFC 6749 §4.1.3 token request (form-encoded). Field requirements are
        grant-dependent: authorization_code needs code (+ redirect_uri +
        code_verifier when PKCE was used); refresh_token needs refresh_token;
        client_credentials may send scope; device_code needs device_code.
        Client auth follows the client's registered
        token_endpoint_auth_method (F-017): client_secret_basic (default)
        -> HTTP Basic ONLY; client_secret_post -> these form fields ONLY;
        'none' (PUBLIC) -> client_id only, secrets rejected.
      properties:
        grant_type:
          type: string
          enum:
          - authorization_code
          - refresh_token
          - client_credentials
          - urn:ietf:params:oauth:grant-type:device_code
        code:
          type: string
          description: Authorization code (required for grant_type=authorization_code).
        redirect_uri:
          type: string
          description: Required for the authorization_code grant.
        refresh_token:
          type: string
          description: Required for grant_type=refresh_token (rotated on use).
        code_verifier:
          type: string
          description: 'PKCE code_verifier (RFC 7636): required for
            authorization_code when the login/authorize request carried a
            code_challenge.'
        client_id:
          type: string
          description: Client identifier (alternative to HTTP Basic authentication).
        client_secret:
          type: string
          description: Client secret for CONFIDENTIAL clients with
            token_endpoint_auth_method=client_secret_post; FORBIDDEN for
            PUBLIC clients whose method is 'none' (F-017).
        scope:
          type: string
          description: Space-separated scopes (client_credentials grant only).
        device_code:
          type: string
          description: Required for the device_code grant (from
            /oauth2/device_authorization).
      required:
      - grant_type
      type: object
    LoginRequest:
      description: /oauth2/login credentials (JSON body or form-encoded; query also accepted).
      properties:
        username:
          type: string
          description: Account username or email.
        password:
          type: string
        client_id:
          type: string
          description: Matches the requesting app (required for code issuance).
        redirect_uri:
          type: string
          description: Must match the registered client.
        scope:
          type: string
          description: Space-separated (optional).
        state:
          type: string
          description: Opaque value maintained between request and callback (recommended).
        code_challenge:
          type: string
          description: PKCE code challenge (RFC 7636). REQUIRED for PUBLIC
            clients (fulla-portal, fulla-admin-console) when
            auth.require_pkce_for_public is enabled (default true, F-011 /
            RFC 9700 §2.1.1). The matching code_verifier must be sent on the
            /oauth2/token exchange.
        code_challenge_method:
          type: string
          description: 'S256 (recommended) or plain.'
        nonce:
          type: string
          description: OIDC nonce (anti-replay), echoed in the id_token.
        json:
          type: string
          description: 'Set to "true" to receive a JSON body instead of a 302 redirect.'
      required:
      - username
      - password
      type: object
    MfaVerifyRequest:
      description: /oauth2/mfa/verify completion payload (JSON body or form-encoded).
      properties:
        mfa_token:
          type: string
          description: The MFA pending token returned by /oauth2/login when
            mfa_required was true.
        code:
          type: string
          description: The 6-digit TOTP code from the user's authenticator.
        client_id:
          type: string
          description: Must match the first-factor login.
        redirect_uri:
          type: string
          description: Must match the first-factor login.
        scope:
          type: string
          description: Defaults to "openid profile email".
        nonce:
          type: string
        code_verifier:
          type: string
          description: PKCE code_verifier matching the code_challenge sent on
            the first-factor /oauth2/login step. Required for PUBLIC clients.
      required:
      - mfa_token
      - code
      - client_id
      - redirect_uri
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    clientCredentialsAuth:
      description: 'OAuth2 client authentication (RFC 6749 §2.3): client_id and client_secret
        via HTTP Basic Authorization header or POST body parameters.'
      scheme: basic
      type: http
info:
  description: OAuth2.0 authorization server with token management
  title: OAuth2 Authorization Server API
  version: 1.6.0
openapi: 3.0.0
paths:
  /.well-known/jwks.json:
    get:
      description: Returns the public keys used by this server to sign JWTs. With a
        signing keystore configured (#110) EVERY loaded key is published so tokens
        keep verifying across the rotation grace window; the active signer is the
        kid the issued JWT headers carry.
      operationId: get_.well-known_jwks.json
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWKSet'
          description: JSON Web Key Set
      summary: JSON Web Key Set
      tags:
      - OpenID Connect
      - Security
  /.well-known/oauth-authorization-server:
    get:
      description: RFC 8414 OAuth 2.0 Authorization Server Metadata. Unlike the OIDC
        discovery document this carries no userinfo/jwks entries.
      operationId: get_.well-known_oauth-authorization-server
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthAuthorizationServerMetadata'
          description: Authorization Server Metadata
      summary: OAuth 2.0 Authorization Server Metadata
      tags:
      - OAuth2
      - Discovery
  /.well-known/openid-configuration:
    get:
      description: Returns OIDC discovery metadata including endpoints and supported
        scopes.
      operationId: get_.well-known_openid-configuration
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIDConfiguration'
          description: OIDC Provider Metadata
      summary: OpenID Connect Discovery
      tags:
      - OpenID Connect
  /api/admin/claim-mappings:
    get:
      description: 'P1-3 (#280): all claim mappings (id_token/userinfo claim
        publication).'
      operationId: get_api_admin_claim_mappings
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  total:
                    type: integer
                  mappings:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        scope_name:
                          type: string
                        claim_name:
                          type: string
                        source_path:
                          type: string
                        include_in:
                          type: string
                        enabled:
                          type: boolean
          description: Mapping list
      security:
      - bearerAuth: []
      summary: List Claim Mappings
      tags:
      - Admin
      - Scopes
    post:
      description: 'P1-3 (#280): map a source (custom_attributes.<key> or
        user.display_name) to a published claim under a trigger scope. Red
        lines: claim_name must not be reserved (CLAIM_MAPPING_RESERVED_CLAIM);
        scope_name must not be openid (CLAIM_MAPPING_FORBIDDEN_SCOPE);
        source_path must be whitelisted (CLAIM_MAPPING_INVALID_SOURCE).'
      operationId: post_api_admin_claim_mappings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - scope_name
              - claim_name
              - source_path
              properties:
                scope_name:
                  type: string
                claim_name:
                  type: string
                source_path:
                  type: string
                include_in:
                  type: string
                  enum:
                  - id_token
                  - userinfo
                  - both
                  default: both
      responses:
        '201':
          description: Mapping created
        '400':
          description: Red-line rejection or invalid shape
      security:
      - bearerAuth: []
      summary: Create Claim Mapping
      tags:
      - Admin
      - Scopes
  /api/admin/claim-mappings/{mappingId}:
    put:
      description: 'P1-3 (#280): update a mapping (full body).'
      operationId: put_api_admin_claim_mappings_{mappingId}
      parameters:
      - description: Mapping ID
        in: path
        name: mappingId
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - scope_name
              - claim_name
              - source_path
              properties:
                scope_name:
                  type: string
                claim_name:
                  type: string
                source_path:
                  type: string
                include_in:
                  type: string
                enabled:
                  type: boolean
      responses:
        '200':
          description: Mapping updated
        '404':
          description: Mapping not found
      security:
      - bearerAuth: []
      summary: Update Claim Mapping
      tags:
      - Admin
      - Scopes
    delete:
      description: 'P1-3 (#280): delete a mapping.'
      operationId: delete_api_admin_claim_mappings_{mappingId}
      parameters:
      - description: Mapping ID
        in: path
        name: mappingId
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Mapping deleted
        '404':
          description: Mapping not found
      security:
      - bearerAuth: []
      summary: Delete Claim Mapping
      tags:
      - Admin
      - Scopes
  /api/admin/clients:
    get:
      description: Get a paginated list of registered OAuth2 clients.
      operationId: get_api_admin_clients
      responses:
        '200':
          description: List of OAuth2 clients
        '401':
          description: Unauthorized
        '403':
          description: 'insufficient_scope / insufficient permissions -- the access
            token lacks the `admin` scope OR the user lacks the admin role (RFC 6750
            §3; on a scope failure accompanied by WWW-Authenticate: Bearer
            error="insufficient_scope", scope="admin"). F-010: /api/admin/* requires
            the `admin` scope in addition to the RBAC admin role.'
      security:
      - bearerAuth: []
      summary: List OAuth2 Clients
      tags:
      - Admin
      - Clients
    post:
      description: Register a new OAuth2 client.
      operationId: post_api_admin_clients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                client_type:
                  type: string
                  enum:
                  - CONFIDENTIAL
                  - PUBLIC
                  default: CONFIDENTIAL
                redirect_uris:
                  type: string
                  description: Comma-separated redirect URIs (https required).
                allowed_grant_types:
                  type: string
                  default: authorization_code
                token_endpoint_auth_method:
                  type: string
                backchannel_logout_uri:
                  type: string
                  format: uri
                  description: OIDC Back-Channel Logout 1.0 RP endpoint. MUST
                    use https (spec §2.3). When set, the OP POSTs a signed
                    logout_token here on user logout.
                logo_uri:
                  type: string
                  maxLength: 512
                  description: 'P1-1 (#279): client brand image for the
                    login/consent screens. https-only (loopback hosts exempt
                    for dev); no userinfo/fragment. NOT the redirect
                    registration rule.'
      responses:
        '201':
          description: Client created successfully
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: Create OAuth2 Client
      tags:
      - Admin
      - Clients
  /api/admin/clients/{clientId}:
    delete:
      description: Delete a specific OAuth2 client.
      operationId: delete_api_admin_clients_{clientId}
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Client deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Client not found
      security:
      - bearerAuth: []
      summary: Delete OAuth2 Client
      tags:
      - Admin
      - Clients
    get:
      description: Get details of a specific OAuth2 client by ID.
      operationId: get_api_admin_clients_{clientId}
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Client details
        '401':
          description: Unauthorized
        '404':
          description: Client not found
      security:
      - bearerAuth: []
      summary: Get Client Details
      tags:
      - Admin
      - Clients
    put:
      description: Update details of a specific OAuth2 client.
      operationId: put_api_admin_clients_{clientId}
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                name:
                  type: string
                redirect_uris:
                  type: string
                allowed_grant_types:
                  type: string
                backchannel_logout_uri:
                  type: string
                  format: uri
                  description: Set to an https URI to enable OIDC back-channel
                    logout notifications to this RP; an empty string clears it.
                logo_uri:
                  type: string
                  maxLength: 512
                  description: 'P1-1 (#279): client brand image (https-only,
                    loopback exempt). An empty string clears it.'
      responses:
        '200':
          description: Client updated successfully
        '400':
          description: Invalid request body
        '401':
          description: Unauthorized
        '404':
          description: Client not found
      security:
      - bearerAuth: []
      summary: Update OAuth2 Client
      tags:
      - Admin
      - Clients
  /api/admin/clients/{clientId}/reset-secret:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Reset the secret of a specific OAuth2 client.
      operationId: post_api_admin_clients_{clientId}_reset-secret
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Client secret reset successfully
        '401':
          description: Unauthorized
        '404':
          description: Client not found
      security:
      - bearerAuth: []
      summary: Reset Client Secret
      tags:
      - Admin
      - Clients
  /api/admin/clients/{clientId}/resume:
    post:
      description: Lift a suspension on a self-registered application (open
        platform governance). Admin-managed clients (no owners row) cannot be
        suspended/resumed here.
      operationId: post_api_admin_clients_{clientId}_resume
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                    client_id:
                      type: string
                    status:
                      type: string
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Not a self-registered application
      security:
      - bearerAuth: []
      summary: Resume Application
      tags:
      - Admin
      - Clients
  /api/admin/clients/{clientId}/scopes:
    get:
      description: Get the assigned scopes for an OAuth2 client.
      operationId: get_api_admin_clients_{clientId}_scopes
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Client scopes retrieved
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: Get Client Scopes
      tags:
      - Admin
      - Clients
    put:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Update the assigned scopes for an OAuth2 client.
      operationId: put_api_admin_clients_{clientId}_scopes
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Client scopes updated successfully
        '400':
          description: Invalid request body
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: Update Client Scopes
      tags:
      - Admin
      - Clients
  /api/admin/clients/{clientId}/suspend:
    post:
      description: Suspend a self-registered application (abuse response).
        While suspended the client validation fails, so no new authorization
        codes or token exchanges succeed. Admin-managed clients (no owners
        row) cannot be suspended here.
      operationId: post_api_admin_clients_{clientId}_suspend
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                    client_id:
                      type: string
                    status:
                      type: string
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Not a self-registered application
      security:
      - bearerAuth: []
      summary: Suspend Application
      tags:
      - Admin
      - Clients
  /api/admin/dashboard:
    get:
      description: Static admin dashboard overview (welcome payload; live numbers
        are on /api/admin/dashboard/stats).
      operationId: get_api_admin_dashboard
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
          description: Dashboard welcome payload
        '401':
          description: Unauthorized
        '403':
          description: 'insufficient permissions -- requires the admin role /
            audit:read scope (F-010).'
      security:
      - bearerAuth: []
      summary: Get Dashboard
      tags:
      - Admin
      - Dashboard
  /api/admin/dashboard/stats:
    get:
      description: Get dashboard statistics including user count, client count, active
        tokens, and failure metrics.
      operationId: get_api_admin_dashboard_stats
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  active_tokens:
                    type: integer
                  failures_today:
                    type: integer
                  logs_today:
                    type: integer
                  status:
                    type: string
                  total_clients:
                    type: integer
                  total_users:
                    type: integer
                type: object
          description: Dashboard statistics
      security:
      - bearerAuth: []
      summary: Get Dashboard Stats
      tags:
      - Admin
      - Dashboard
  /api/admin/email-templates:
    get:
      description: 'P1-2 (#278): list all email templates (template_key x locale).
        Memory-storage deployments answer 404 (no template store).'
      operationId: get_api_admin_email_templates
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                  total:
                    type: integer
                  templates:
                    type: array
                    items:
                      type: object
                      properties:
                        template_key:
                          type: string
                        locale:
                          type: string
                        subject:
                          type: string
                        body_html:
                          type: string
                        body_text:
                          type: string
                        updated_at:
                          type: string
                type: object
          description: Email template list
        '404':
          description: Memory mode (no template store)
      security:
      - bearerAuth: []
      summary: List Email Templates
      tags:
      - Admin
      - Email
  /api/admin/email-templates/{key}/{locale}:
    get:
      description: Fetch one email template by key and locale.
      operationId: get_api_admin_email_templates_{key}_{locale}
      parameters:
      - description: Template key (e.g. email_verification, password_reset, org_invitation)
        in: path
        name: key
        required: true
        schema:
          type: string
      - description: 'Locale tag (BCP47-light: e.g. en, zh-CN)'
        in: path
        name: locale
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Template row (subject/body_html/body_text/updated_at)
        '404':
          description: 'No row for key/locale (EMAIL_TEMPLATE_NOT_FOUND)'
      security:
      - bearerAuth: []
      summary: Get Email Template
      tags:
      - Admin
      - Email
    put:
      description: 'Create or update a template. Save-time content policy rejects
        script/iframe/form/object/embed/base tags, javascript:/data:/vbscript: URLs,
        and outbound http(s) links outside the configured email.allowed_link_domains
        (EMAIL_TEMPLATE_CONTENT_REJECTED). Variables use {{name}} placeholders;
        substituted values are HTML-escaped by the engine.'
      operationId: put_api_admin_email_templates_{key}_{locale}
      parameters:
      - description: Template key
        in: path
        name: key
        required: true
        schema:
          type: string
      - description: Locale tag (e.g. en, zh-CN)
        in: path
        name: locale
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - subject
              - body_html
              properties:
                subject:
                  type: string
                  maxLength: 256
                body_html:
                  type: string
                  maxLength: 65536
                body_text:
                  type: string
                  maxLength: 65536
      responses:
        '200':
          description: Template saved (audited as email_template_updated)
        '400':
          description: 'Validation failure or content policy rejection (EMAIL_TEMPLATE_CONTENT_REJECTED)'
      security:
      - bearerAuth: []
      summary: Upsert Email Template
      tags:
      - Admin
      - Email
  /api/admin/email-templates/{key}/{locale}/test-send:
    post:
      description: 'Render a template with synthetic sample variables (no real user
        PII) and send it. Recipient must be the admin''s own address or listed in
        email.test_recipients (EMAIL_TEST_RECIPIENT_DENIED); rolling-24h per-admin
        quota applies (EMAIL_TEST_QUOTA_EXCEEDED, email.test_send_quota_per_day,
        default 10). Audited as email_test_sent.'
      operationId: post_api_admin_email_templates_{key}_{locale}_test_send
      parameters:
      - description: Template key
        in: path
        name: key
        required: true
        schema:
          type: string
      - description: Locale tag (e.g. en, zh-CN)
        in: path
        name: locale
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - to
              properties:
                to:
                  type: string
                  format: email
      responses:
        '200':
          description: Test email sent (response carries the rendered subject)
        '403':
          description: 'Recipient not whitelisted (EMAIL_TEST_RECIPIENT_DENIED)'
        '404':
          description: 'Template not found (EMAIL_TEMPLATE_NOT_FOUND) or memory mode'
        '429':
          description: 'Rolling-24h quota reached (EMAIL_TEST_QUOTA_EXCEEDED)'
      security:
      - bearerAuth: []
      summary: Test-send Email Template
      tags:
      - Admin
      - Email
  /api/admin/logs:
    get:
      description: Get a paginated list of system audit logs.
      operationId: get_api_admin_logs
      responses:
        '200':
          description: Audit logs list
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: List Audit Logs
      tags:
      - Admin
      - Logs
  /api/admin/logs/export:
    get:
      description: 'P1-6 (#283): CSV export of the audit trail. Same filters as the
        list endpoint (action/outcome/actor_id) plus a mandatory time window (from/to,
        epoch seconds) unless an explicit all=true is given; row cap (audit.export_max_rows,
        default 500k; the per-request `limit` may only lower it) — over-cap answers
        400 AUDIT_EXPORT_TOO_LARGE. Cells are formula-injection hardened (leading
        = + - @ tab CR get a '''' prefix). Audited as audit_exported. Memory deployments
        answer 404.'
      operationId: get_api_admin_logs_export
      parameters:
      - description: Filter by action
        in: query
        name: action
        required: false
        schema:
          type: string
      - description: Filter by outcome
        in: query
        name: outcome
        required: false
        schema:
          type: string
      - description: Filter by actor id
        in: query
        name: actor_id
        required: false
        schema:
          type: string
      - description: Window start (unix epoch seconds); required unless all=true
        in: query
        name: from
        required: false
        schema:
          type: integer
          format: int64
      - description: Window end (unix epoch seconds); required unless all=true
        in: query
        name: to
        required: false
        schema:
          type: integer
          format: int64
      - description: 'Explicit full-table opt-in (window requirement waived; the row
        cap still applies)'
        in: query
        name: all
        required: false
        schema:
          type: string
          enum:
          - "true"
          - "1"
      - description: Max rows to export (may only lower audit.export_max_rows)
        in: query
        name: limit
        required: false
        schema:
          type: integer
          format: int64
          minimum: 1
      responses:
        '200':
          content:
            text/csv:
              schema:
                type: string
          description: CSV file (attachment)
        '400':
          description: 'Missing window (AUDIT_EXPORT_WINDOW_REQUIRED) or over-cap
            (AUDIT_EXPORT_TOO_LARGE)'
        '404':
          description: Memory mode (no audit store)
      security:
      - bearerAuth: []
      summary: Export Audit Logs (CSV)
      tags:
      - Admin
      - Logs
  /api/admin/oidc/keys:
    get:
      description: 'Live signing-keystore state (#110): every loaded kid with its
        status (active = signs new tokens, published = verification-only during a
        rotation grace window), the active_kid, and the key count. Cryptographic
        material (n/e) lives in /.well-known/jwks.json.'
      operationId: get_api_admin_oidc_keys
      responses:
        '200':
          description: OIDC signing key information
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: Get OIDC Keys Info
      tags:
      - Admin
      - OIDC
  /api/admin/organizations:
    get:
      description: List all organizations (id, slug, name, branding fields; no created_at).
      operationId: get_api_admin_organizations
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
                  total:
                    type: integer
          description: Organizations list
        '401':
          description: Unauthorized
        '403':
          description: insufficient permissions (roles:read, implied by admin)
      security:
      - bearerAuth: []
      summary: List Organizations
      tags:
      - Admin
      - Organization
    post:
      description: Create an organization. Slug must be 3-50 chars of lowercase
        alphanumeric + hyphens, starting/ending alphanumeric.
      operationId: post_api_admin_organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - slug
              - name
              properties:
                slug:
                  type: string
                  pattern: '^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$'
                name:
                  type: string
                logo_uri:
                  type: string
                primary_color:
                  type: string
                issuer_override:
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Organization'
                - type: object
                  properties:
                    message:
                      type: string
          description: Organization created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: 'Validation error: missing/invalid JSON body, bad slug, or missing name'
        '401':
          description: Unauthorized
        '409':
          description: Organization slug already exists (or DB error)
      security:
      - bearerAuth: []
      summary: Create Organization
      tags:
      - Admin
      - Organization
  /api/admin/organizations/{slug}:
    get:
      description: Get a single organization by its slug.
      operationId: get_api_admin_organizations_{slug}
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
          description: Organization details
        '401':
          description: Unauthorized
        '404':
          description: Organization not found
      security:
      - bearerAuth: []
      summary: Get Organization
      tags:
      - Admin
      - Organization
    delete:
      description: 'P1-4 (#281): soft delete with a CLOSED cascade (one
        transaction): slug rewritten to a #del-<id> placeholder (no slug
        reuse), pending invitations and succession nominations voided, org
        consents revoked, owned clients suspended (their outstanding tokens
        introspect inactive), memberships detached. Audited as org_deleted.'
      operationId: delete_api_admin_organizations_{slug}
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization deleted (soft)
        '401':
          description: Unauthorized
        '404':
          description: Organization not found (or already deleted)
      security:
      - bearerAuth: []
      summary: Delete Organization
      tags:
      - Admin
      - Organization
    patch:
      description: 'P1-4 (#281): edit name/logo_uri/primary_color (slug is
        immutable — external reference anchor). Brand fields validated with
        the P1-1 rules (https-only logo + loopback exemption; color
        ^#[0-9a-fA-F]{3,6}$). Audited as org_updated.'
      operationId: patch_api_admin_organizations_{slug}
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                logo_uri:
                  type: string
                  maxLength: 512
                  description: https-only (loopback exempt); empty clears.
                primary_color:
                  type: string
                  pattern: '^#[0-9a-fA-F]{3,6}$'
                  description: Empty clears.
      responses:
        '200':
          description: Organization updated
        '400':
          description: Invalid field values or slug change attempted
        '404':
          description: Organization not found
      security:
      - bearerAuth: []
      summary: Update Organization
      tags:
      - Admin
      - Organization
  /api/admin/organizations/{slug}/members:
    get:
      description: 'P1-4 (#281): read-only member roster (user_id, username,
        role, joined_at).'
      operationId: get_api_admin_organizations_{slug}_members
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  total:
                    type: integer
                  members:
                    type: array
                    items:
                      type: object
                      properties:
                        user_id:
                          type: integer
                        username:
                          type: string
                        role:
                          type: string
                        joined_at:
                          type: string
          description: Member roster
        '404':
          description: Organization not found
      security:
      - bearerAuth: []
      summary: List Organization Members
      tags:
      - Admin
      - Organization
  /api/admin/organizations/{slug}/members/{userId}:
    delete:
      description: 'P1-4 (#281): remove a membership. Removing the last owner
        is rejected (409) — transfer ownership first. Audited as
        org_member_removed.'
      operationId: delete_api_admin_organizations_{slug}_members_{userId}
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      - description: User id
        in: path
        name: userId
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Member removed
        '404':
          description: Organization or membership not found
        '409':
          description: Last owner (transfer ownership first)
      security:
      - bearerAuth: []
      summary: Remove Organization Member
      tags:
      - Admin
      - Organization
  /api/admin/organizations/{slug}/transfer-ownership:
    post:
      description: Reassign the organization's owner seat to a live user (#221
        admin override). The target is promoted (or added) as owner; previous
        owner rows are demoted to admin. Resolves the soft-deleted-owner
        deadlock where an org becomes unmanageable.
      operationId: post_api_admin_organizations_{slug}_transfer_ownership
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user_id
              properties:
                user_id:
                  type: integer
                  format: int32
                  description: ID of the live user who becomes the new owner
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                  organization_id:
                    type: integer
                  owner_user_id:
                    type: integer
          description: Ownership transferred
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: 'Validation error: missing/invalid JSON body or user_id'
        '401':
          description: Unauthorized
        '404':
          description: Organization or target user not found (or soft-deleted)
        '409':
          description: The target left the organization during the transfer
            (VALIDATION_RESOURCE_CONFLICT; retry with a current member)
        '500':
          description: The promote succeeded but the demotion of previous
            owner rows failed (DB_QUERY_ERROR) — the org may temporarily have
            two owners; retrying the same transfer is safe
      security:
      - bearerAuth: []
      summary: Transfer Organization Ownership
      tags:
      - Admin
      - Organization
  /api/admin/roles:
    get:
      description: Get a list of all roles with user counts.
      operationId: get_api_admin_roles
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  roles:
                    items:
                      properties:
                        created_at:
                          type: string
                        description:
                          type: string
                        id:
                          type: integer
                        name:
                          type: string
                        user_count:
                          type: integer
                      type: object
                    type: array
                  status:
                    type: string
                  total:
                    type: integer
                type: object
          description: Roles list
      security:
      - bearerAuth: []
      summary: List Roles
      tags:
      - Admin
      - Roles
    post:
      description: Create a new role. Built-in roles (admin, user) cannot be duplicated.
      operationId: post_api_admin_roles
      requestBody:
        content:
          application/json:
            schema:
              properties:
                description:
                  type: string
                name:
                  type: string
              required:
              - name
              type: object
      responses:
        '201':
          description: Role created successfully
        '400':
          description: Invalid request
        '409':
          description: Role name already exists
      security:
      - bearerAuth: []
      summary: Create Role
      tags:
      - Admin
      - Roles
  /api/admin/roles/{roleId}/permissions:
    get:
      description: 'P1-8 (#285): the role''s permission set (delegated
        administration surface).'
      operationId: get_api_admin_roles_{roleId}_permissions
      parameters:
      - description: Role ID
        in: path
        name: roleId
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  total:
                    type: integer
                  permissions:
                    type: array
                    items:
                      type: string
          description: Permission-name list
        '404':
          description: Role not found
      security:
      - bearerAuth: []
      summary: List Role Permissions
      tags:
      - Admin
      - Roles
    put:
      description: 'P1-8 (#285): FULL-REPLACE the role''s permission set.
        Every listed name must exist in the permissions catalog; unknown
        names fail the whole replace. Audited as role_permissions_updated;
        the role-permission cache entry is invalidated on commit.'
      operationId: put_api_admin_roles_{roleId}_permissions
      parameters:
      - description: Role ID
        in: path
        name: roleId
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - permissions
              properties:
                permissions:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Role permissions updated
        '400':
          description: Invalid body or unknown permission names
        '404':
          description: Role not found
      security:
      - bearerAuth: []
      summary: Replace Role Permissions
      tags:
      - Admin
      - Roles
  /api/admin/roles/{roleId}:
    delete:
      description: Delete a role. Built-in roles (admin, user) cannot be deleted.
      operationId: delete_api_admin_roles_{roleId}
      parameters:
      - description: Role ID
        in: path
        name: roleId
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Role deleted successfully
        '404':
          description: Role not found or is built-in
      security:
      - bearerAuth: []
      summary: Delete Role
      tags:
      - Admin
      - Roles
    put:
      description: Update a role's description.
      operationId: put_api_admin_roles_{roleId}
      parameters:
      - description: Role ID
        in: path
        name: roleId
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                description:
                  type: string
              type: object
      responses:
        '200':
          description: Role updated successfully
        '404':
          description: Role not found
      security:
      - bearerAuth: []
      summary: Update Role
      tags:
      - Admin
      - Roles
  /api/admin/scopes:
    get:
      description: Get a list of all available scopes.
      operationId: get_api_admin_scopes
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  scopes:
                    items:
                      properties:
                        description:
                          type: string
                        id:
                          type: integer
                        is_default:
                          type: boolean
                        mapped_role:
                          type: string
                        name:
                          type: string
                        requires_admin_role:
                          type: boolean
                      type: object
                    type: array
                  status:
                    type: string
                  total:
                    type: integer
                type: object
          description: Scopes list
      security:
      - bearerAuth: []
      summary: List Scopes
      tags:
      - Admin
      - Scopes
    post:
      description: Create a new OAuth2 scope. Built-in scopes cannot be duplicated.
      operationId: post_api_admin_scopes
      requestBody:
        content:
          application/json:
            schema:
              properties:
                description:
                  type: string
                  maxLength: 512
                description_zh:
                  type: string
                  maxLength: 512
                  description: 'P1-1 (#279): zh-CN consent-screen copy.'
                is_default:
                  type: boolean
                mapped_role:
                  type: string
                name:
                  type: string
                requires_admin_role:
                  type: boolean
              required:
              - name
              type: object
      responses:
        '201':
          description: Scope created successfully
        '400':
          description: Invalid request
        '409':
          description: Scope name already exists
      security:
      - bearerAuth: []
      summary: Create Scope
      tags:
      - Admin
      - Scopes
  /api/admin/scopes/{scopeId}:
    delete:
      description: Delete a scope. Built-in scopes (openid, profile, email, admin)
        cannot be deleted.
      operationId: delete_api_admin_scopes_{scopeId}
      parameters:
      - description: Scope ID
        in: path
        name: scopeId
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Scope deleted successfully
        '404':
          description: Scope not found or is built-in
      security:
      - bearerAuth: []
      summary: Delete Scope
      tags:
      - Admin
      - Scopes
    put:
      description: Update a scope's properties.
      operationId: put_api_admin_scopes_{scopeId}
      parameters:
      - description: Scope ID
        in: path
        name: scopeId
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                description:
                  type: string
                  maxLength: 512
                description_zh:
                  type: string
                  maxLength: 512
                  description: 'P1-1 (#279): zh-CN consent-screen copy; the
                    consent context serves it for zh pages. Empty clears it.
                    Description changes are audited with a before/after diff.'
                is_default:
                  type: boolean
                mapped_role:
                  type: string
                requires_admin_role:
                  type: boolean
              type: object
      responses:
        '200':
          description: Scope updated successfully
        '404':
          description: Scope not found
      security:
      - bearerAuth: []
      summary: Update Scope
      tags:
      - Admin
      - Scopes
  /api/admin/scopes/resources:
    get:
      description: '#43 discovery -- the (path, method) -> required-scopes matrix
        from the central ResourceScopeRegistry. Read-only, no DB access.'
      operationId: get_api_admin_scopes_resources
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  resources:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        method:
                          type: string
                        required_scopes:
                          type: array
                          items:
                            type: string
                        implied_by:
                          type: array
                          items:
                            type: string
          description: Scope-resource matrix
      security:
      - bearerAuth: []
      summary: Scope-Resource Matrix
      tags:
      - Admin
      - Scopes
  /api/admin/tokens:
    get:
      description: Get a list of active OAuth2 tokens.
      operationId: get_api_admin_tokens
      responses:
        '200':
          description: Tokens list
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: List Tokens
      tags:
      - Admin
      - Tokens
  /api/admin/tokens/revoke-by-client:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Revoke all tokens issued to a specific client.
      operationId: post_api_admin_tokens_revoke-by-client
      responses:
        '200':
          description: Tokens revoked successfully
        '400':
          description: Invalid request body
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: Revoke Tokens By Client
      tags:
      - Admin
      - Tokens
  /api/admin/tokens/revoke-by-user:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Revoke all tokens issued for a specific user.
      operationId: post_api_admin_tokens_revoke-by-user
      responses:
        '200':
          description: Tokens revoked successfully
        '400':
          description: Invalid request body
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: Revoke Tokens By User
      tags:
      - Admin
      - Tokens
  /api/admin/tokens/{tokenPrefix}:
    delete:
      description: Revoke a specific token by its prefix.
      operationId: delete_api_admin_tokens_{tokenPrefix}
      parameters:
      - description: Token prefix
        in: path
        name: tokenPrefix
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Token revoked successfully
        '401':
          description: Unauthorized
        '404':
          description: Token not found
      security:
      - bearerAuth: []
      summary: Revoke Token
      tags:
      - Admin
      - Tokens
  /api/admin/users:
    get:
      description: >-
        List users with optional pagination (page, per_page) and filtering
        (q for username/email prefix, role, locked). Returns total count.
      operationId: get_api_admin_users
      parameters:
      - description: Page number (1-based)
        in: query
        name: page
        required: false
        schema:
          type: integer
          default: 1
      - description: Items per page (1-100)
        in: query
        name: per_page
        required: false
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 100
      - description: Search by username or email prefix
        in: query
        name: q
        required: false
        schema:
          type: string
      - description: Filter by role name
        in: query
        name: role
        required: false
        schema:
          type: string
      - description: Filter by lock state (true = locked, false = active)
        in: query
        name: locked
        required: false
        schema:
          type: string
          enum: ["true", "false"]
      responses:
        '200':
          description: Users list
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: List Users
      tags:
      - Admin
      - Users
    post:
      description: >-
        Create a new user. Requires username and password; email, roles,
        mfa_enabled, email_verified, and must_change_password are optional.
        must_change_password (default false, #145) forces the user to change
        the password at first login. The deprecated users.org_id column is
        read-only since v1.4.0: requests containing org_id are rejected with
        400 (organization membership is managed via the organization APIs).
      operationId: post_api_admin_users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                password:
                  type: string
                  format: password
                email:
                  type: string
                email_verified:
                  type: boolean
                mfa_enabled:
                  type: boolean
                must_change_password:
                  type: boolean
                  description: 'Force a password change at first login (#145);
                    while flagged, no authorization codes are issued for the
                    account. Default false.'
                roles:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: >-
            User created successfully. The response body reports role
            assignment outcome: roles_assigned (names landed), roles_failed
            (requested names that did not land — unresolved or insert
            failures), and a warning field when roles_failed is non-empty.
        '400':
          description: Validation error
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - bearerAuth: []
      summary: Create User
      tags:
      - Admin
      - Users
  /api/admin/users/{userId}:
    delete:
      description: >-
        Soft-delete a user account (sets deleted_at). The user is excluded
        from all queries and can no longer log in. Outstanding access and
        refresh tokens are revoked (matched on both the public subject and
        the internal id) before the response is sent; the 200 body reports
        tokens_revoked (false + warning on revocation failure).
      operationId: delete_api_admin_users_{userId}
      parameters:
      - description: User ID
        in: path
        name: userId
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: User deleted successfully (see tokens_revoked in the body)
        '400':
          description: Cannot delete your own account
        '404':
          description: User not found
        '409':
          description: The target is the last active admin
      security:
      - bearerAuth: []
      summary: Delete User
      tags:
      - Admin
      - Users
    get:
      description: Get detailed information about a specific user including roles and
        account status.
      operationId: get_api_admin_users_{userId}
      parameters:
      - description: User ID
        in: path
        name: userId
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    type: string
                  email:
                    type: string
                  email_verified:
                    type: boolean
                  failed_login_count:
                    type: integer
                  id:
                    type: integer
                  locked:
                    type: boolean
                  locked_until:
                    type: integer
                  mfa_enabled:
                    type: boolean
                  org_id:
                    type: integer
                    nullable: true
                  roles:
                    items:
                      type: string
                    type: array
                  status:
                    type: string
                  username:
                    type: string
                type: object
          description: User details (org_id is a deprecated read-only legacy column since v1.4.0; null when unset)
        '404':
          description: User not found
      security:
      - bearerAuth: []
      summary: Get User Detail
      tags:
      - Admin
      - Users
    put:
      description: >-
        Update user information. Updatable fields: username, email,
        email_verified, mfa_enabled, must_change_password (#145; enforcement
        starts at the user's next login), and locked (true locks the account).
        Fields with a wrong JSON type are rejected with 400 (never silently
        skipped). The deprecated users.org_id column is read-only since
        v1.4.0: requests containing org_id are rejected with 400 (organization
        membership is managed via the organization APIs).
      operationId: put_api_admin_users_{userId}
      parameters:
      - description: User ID
        in: path
        name: userId
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                username:
                  type: string
                email:
                  type: string
                email_verified:
                  type: boolean
                mfa_enabled:
                  type: boolean
                must_change_password:
                  type: boolean
                  description: 'Set/clear the forced password-change flag (#145);
                    enforcement starts at the user''s next login.'
                locked:
                  type: boolean
              type: object
      responses:
        '200':
          description: User updated successfully
        '400':
          description: Invalid field type or no updatable fields provided
        '404':
          description: User not found
        '409':
          description: >-
            Conflict — the target is the last active admin and the update
            would lock them out of the management plane (e.g. locked=true)
      security:
      - bearerAuth: []
      summary: Update User
      tags:
      - Admin
      - Users
  /api/admin/users/{userId}/disable:
    put:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Disable a specific user account.
      operationId: put_api_admin_users_{userId}_disable
      parameters:
      - description: User ID
        in: path
        name: userId
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: User disabled successfully
        '401':
          description: Unauthorized
        '404':
          description: User not found
        '409':
          description: The target is the last active admin
      security:
      - bearerAuth: []
      summary: Disable User
      tags:
      - Admin
      - Users
  /api/admin/users/{userId}/enable:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Enable a disabled user account by resetting lockout state.
      operationId: post_api_admin_users_{userId}_enable
      parameters:
      - description: User ID
        in: path
        name: userId
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: User enabled successfully
        '404':
          description: User not found
      security:
      - bearerAuth: []
      summary: Enable User
      tags:
      - Admin
      - Users
  /api/admin/users/{userId}/roles:
    get:
      description: Get the roles assigned to a specific user.
      operationId: get_api_admin_users_{userId}_roles
      parameters:
      - description: User ID
        in: path
        name: userId
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  roles:
                    items:
                      properties:
                        description:
                          type: string
                        id:
                          type: integer
                        name:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: User roles retrieved
        '404':
          description: User not found
      security:
      - bearerAuth: []
      summary: Get User Roles
      tags:
      - Admin
      - Users
    put:
      description: Assign roles to a specific user.
      operationId: put_api_admin_users_{userId}_roles
      parameters:
      - description: User ID
        in: path
        name: userId
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                roles:
                  items:
                    type: string
                  type: array
              required:
              - roles
              type: object
      responses:
        '200':
          description: Roles assigned successfully
        '400':
          description: Invalid request body
        '409':
          description: >-
            The change would remove the admin role from the last active admin
      security:
      - bearerAuth: []
      summary: Assign User Roles
      tags:
      - Admin
      - Users
  /api/auth/providers:
    get:
      description: Public, unauthenticated discovery of the external login
        providers this deployment currently offers (v1.4.0 provider tiers).
        The login page renders its provider buttons from this response; an
        empty list means external login is disabled. authorize_url is the
        fully built provider authorize URL — the SPA redirects to it as-is;
        the redirect target resolves from the per-provider redirect_uri
        override, else frontend.url + /callback/{provider}.
      operationId: get_api_auth_providers
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProvidersResponse'
          description: Currently enabled external login providers (empty array
            when external login is off).
      summary: List Enabled External Login Providers
      tags:
      - External Auth
  /api/github/login:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Exchange GitHub authorization code for user information. This endpoint
        handles the server-side OAuth2 flow with GitHub.
      operationId: post_api_github_login
      parameters:
      - description: Authorization code from GitHub OAuth2 callback (required)
        in: query
        name: code
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialLoginTokenResponse'
          description: First-party token pair issued for the GitHub-linked local account. (Spec correction #70 - the previously documented profile object was stale; the runtime has returned tokens since the account-linking flow landed.)
        '400':
          description: Invalid request (missing or invalid code)
        '403':
          description: Provider identity is not linked to a local account and first-login auto-create is disabled (AUTH_SOCIAL_ACCOUNT_NOT_LINKED)
        '502':
          description: Failed to contact GitHub API
      summary: GitHub OAuth2 Login
      tags:
      - External Auth
      - GitHub
  /api/google/login:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Exchange Google authorization code for user information. This endpoint
        handles the server-side OAuth2 flow with Google Identity Platform.
      operationId: post_api_google_login
      parameters:
      - description: Authorization code from Google OAuth2 callback (required)
        in: query
        name: code
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                access_token: eyJhbGciOi...
                expires_in: 3600
                refresh_token: eyJhbGciOi...
                token_type: Bearer
              schema:
                $ref: '#/components/schemas/SocialLoginTokenResponse'
          description: First-party token pair issued for the Google-linked local account (the pre-#70 profile-only object is still returned when the service runs without an account repository - degraded mode, not the deployed configuration)
        '400':
          content:
            application/json:
              example:
                error: Missing code parameter
          description: Invalid request (missing or invalid code)
        '403':
          description: Provider identity is not linked to a local account and first-login auto-create is disabled (AUTH_SOCIAL_ACCOUNT_NOT_LINKED)
        '502':
          description: Failed to contact Google API
      summary: Google OAuth2 Login
      tags:
      - External Auth
      - Google
  /api/me:
    delete:
      description: Soft-delete the current user's account.
      operationId: delete_api_me
      responses:
        '200':
          description: Account deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: User not found
      security:
      - bearerAuth: []
      summary: Delete Account
      tags:
      - User Profile
    get:
      description: Get current user's profile information. The 200 body includes
        username, email, email_verified, mfa_enabled, and must_change_password
        (#145; true while the account must change its password at first login).
      operationId: get_api_me
      responses:
        '200':
          description: User profile
        '401':
          description: Unauthorized
        '403':
          description: 'insufficient_scope -- the access token lacks the `profile`
            scope (RFC 6750 §3; accompanied by WWW-Authenticate: Bearer
            error="insufficient_scope", scope="profile"). F-010.'
        '404':
          description: User not found
      security:
      - bearerAuth: []
      summary: Get User Profile
      tags:
      - User Profile
  /api/me/authorized-apps:
    get:
      description: List OAuth2 clients authorized by the current user.
      operationId: get_api_me_authorized-apps
      responses:
        '200':
          description: Authorized apps list
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: List Authorized Apps
      tags:
      - User Profile
  /api/me/authorized-apps/{clientId}:
    delete:
      description: Revoke the current user's authorization for a specific OAuth2 client.
      operationId: delete_api_me_authorized-apps_{clientId}
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Authorization revoked successfully
        '401':
          description: Unauthorized
        '404':
          description: User not found
      security:
      - bearerAuth: []
      summary: Revoke App Authorization
      tags:
      - User Profile
  /api/me/applications:
    get:
      description: List the caller's self-registered applications (personal
        plus org apps the caller can manage). Secrets are never included.
      operationId: get_api_me_applications
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  applications:
                    type: array
                    items:
                      type: object
                      properties:
                        client_id:
                          type: string
                        name:
                          type: string
                        client_type:
                          type: string
                          enum: [PUBLIC, CONFIDENTIAL]
                        status:
                          type: string
                          enum: [active, suspended]
                        org_id:
                          type: integer
                          nullable: true
                        creator_user_id:
                          type: integer
                        redirect_uris:
                          type: array
                          items:
                            type: string
                        allowed_grant_types:
                          type: array
                          items:
                            type: string
                        created_at:
                          type: string
                  total:
                    type: integer
          description: Applications list
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: List My Applications
      tags:
      - Applications
    post:
      description: Register an OAuth2/OIDC application (RP self-registration;
        v1.4.0 open platform). Gated by the open_platform config (enabled,
        require_org, per-user/per-org quotas, 24h creation rate limit, the
        self_service scope allowlist and the grant-type whitelist). The
        client secret (CONFIDENTIAL) is returned exactly once.
      operationId: post_api_me_applications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                client_type:
                  type: string
                  enum: [PUBLIC, CONFIDENTIAL]
                redirect_uris:
                  type: array
                  items:
                    type: string
                scopes:
                  type: array
                  items:
                    type: string
                allowed_grant_types:
                  type: array
                  items:
                    type: string
                org_slug:
                  type: string
                  description: Register under this organization (caller must
                    be its owner/admin); omit for a personal application.
                logo_uri:
                  type: string
                  maxLength: 512
                  description: 'P1-1 (#279): application brand image for the
                    login/consent screens (https-only, loopback hosts exempt).'
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_id:
                    type: string
                  client_type:
                    type: string
                    enum: [PUBLIC, CONFIDENTIAL]
                  client_secret:
                    type: string
                    description: Present exactly once for CONFIDENTIAL apps.
                  org_id:
                    type: integer
                  message:
                    type: string
          description: Application created (client_secret present once)
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid input (scope/grant/redirect validation)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Open platform disabled / org registration required
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization not found (#229 — an org_slug the caller cannot manage returns the same 404)
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Quota exceeded
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Creation rate limit reached
      security:
      - bearerAuth: []
      summary: Register Application (self-service)
      tags:
      - Applications
  /api/me/applications/{clientId}:
    delete:
      description: Soft-delete a self-registered application; it disappears
        from every flow immediately (authorization, token, introspection).
      operationId: delete_api_me_applications_{clientId}
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                    message:
                      type: string
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Application not found (or caller cannot manage it; #223 uniform 404)
      security:
      - bearerAuth: []
      summary: Delete Application
      tags:
      - Applications
    patch:
      description: Update name / redirect_uris / allowed_grant_types / scopes
        / logo_uri of a self-registered application (personal apps are
        managed by the creator, org apps by org owner/admin members). Absent
        keys are left unchanged.
      operationId: patch_api_me_applications_{clientId}
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                name:
                  type: string
                  maxLength: 100
                redirect_uris:
                  type: array
                  items:
                    type: string
                allowed_grant_types:
                  type: array
                  items:
                    type: string
                scopes:
                  type: array
                  items:
                    type: string
                logo_uri:
                  type: string
                  maxLength: 512
                  description: 'P1-1 (#279): application brand image
                    (https-only, loopback hosts exempt). An empty string
                    clears it.'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                    message:
                      type: string
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid input
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Application is suspended (management writes are frozen)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Application not found
      security:
      - bearerAuth: []
      summary: Update Application
      tags:
      - Applications
  /api/me/applications/{clientId}/rotate-secret:
    post:
      description: Rotate the client secret of a CONFIDENTIAL self-registered
        application. The previous secret is invalidated immediately; the new
        secret is returned exactly once.
      operationId: post_api_me_applications_{clientId}_rotate-secret
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_id:
                    type: string
                  client_secret:
                    type: string
                    description: Present exactly once.
                  message:
                    type: string
          description: Secret rotated (client_secret present once)
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: PUBLIC clients have no secret
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Application is suspended (management writes are frozen)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Application not found
      security:
      - bearerAuth: []
      summary: Rotate Application Secret
      tags:
      - Applications
  /api/me/applications/{clientId}/transfer:
    post:
      description: Move the management anchor. Send org_slug set to an
        organization slug the caller manages, or org_slug null to move back
        to personal. The client_id, existing consents and issued tokens are
        preserved.
      operationId: post_api_me_applications_{clientId}_transfer
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [org_slug]
              properties:
                org_slug:
                  type: string
                  nullable: true
                  description: Target organization slug, or null to transfer
                    back to personal ownership.
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                    message:
                      type: string
                    org_id:
                      type: integer
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid input
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Application is suspended, or caller lacks the manager role on the target organization
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Application or organization not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Quota exceeded
      security:
      - bearerAuth: []
      summary: Transfer Application
      tags:
      - Applications
  /api/me/mfa/disable:
    post:
      description: Disable MFA (TOTP) for the authenticated user.
      operationId: post_api_me_mfa_disable
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
          description: MFA disabled successfully
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing/invalid Bearer token
      security:
      - bearerAuth: []
      summary: Disable MFA
      tags:
      - MFA
  /api/me/mfa/setup:
    post:
      description: Initiate MFA setup by generating a TOTP secret. Returns the base32
        secret and an otpauth:// URI for authenticator apps / QR codes.
      operationId: post_api_me_mfa_setup
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  secret:
                    type: string
                    description: Base32 TOTP shared secret.
                  otpauth_uri:
                    type: string
                    description: otpauth:// provisioning URI (encode as QR for authenticators).
                  message:
                    type: string
                required:
                - secret
                - otpauth_uri
          description: MFA setup initiated
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing/invalid Bearer token
      security:
      - bearerAuth: []
      summary: Setup MFA
      tags:
      - MFA
  /api/me/mfa/verify:
    post:
      description: Verify a 6-digit TOTP code to finalize MFA setup. Returns 10
        single-use backup codes on success.
      operationId: post_api_me_mfa_verify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  description: 6-digit TOTP code from the user's authenticator.
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  backup_codes:
                    type: array
                    items:
                      type: string
                    description: 10 single-use backup codes.
                  warning:
                    type: string
          description: MFA enabled successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing or non-6-digit code
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing/invalid Bearer token, MFA not configured, or wrong code
      security:
      - bearerAuth: []
      summary: Verify MFA Setup
      tags:
      - MFA
  /api/me/org-invitations/accept:
    post:
      description: Accept an organization invitation by token. The caller's
        account email must match the invitation email (normalized); the
        invitation is single-use and expires after 72h.
      operationId: post_api_me_org-invitations_accept
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization_id:
                    type: integer
                  role:
                    type: string
                  message:
                    type: string
          description: Invitation accepted
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing token or expired invitation
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Issued to a different email address, or email not verified
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid token
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invitation already accepted or caller already a member
      security:
      - bearerAuth: []
      summary: Accept Organization Invitation
      tags:
      - Organization
  /api/me/organizations:
    get:
      description: List the current user's organization memberships, including
        the caller's org role (owner/admin/member).
      operationId: get_api_me_organizations
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        slug:
                          type: string
                        name:
                          type: string
                        logo_uri:
                          type: string
                        primary_color:
                          type: string
                        role:
                          type: string
                          enum: [owner, admin, member]
                        successor_nomination:
                          description: The org's pending succession nomination;
                            visible to owner/admin callers only (null otherwise).
                          type: object
                          nullable: true
                          properties:
                            nominee_user_id:
                              type: integer
                            nominated_by:
                              type: integer
                            created_at:
                              type: string
                  total:
                    type: integer
                  pending_succession_nominations:
                    description: Orgs where the CALLER is the pending nominee
                      (the accept banner's discovery surface; the caller may be
                      a non-member). v1.4.0 M3.
                    type: array
                    items:
                      type: object
                      properties:
                        organization_id:
                          type: integer
                        slug:
                          type: string
                        name:
                          type: string
                        created_at:
                          type: string
          description: Organization memberships
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: List My Organizations
      tags:
      - Organization
    post:
      description: Create an organization (self-service, v1.4.0); the caller
        becomes its owner. Slug rules match the admin endpoint; a reserved
        slug list applies; per-user org quota defaults to 3.
      operationId: post_api_me_organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [slug, name]
              properties:
                slug:
                  type: string
                  pattern: '^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$'
                name:
                  type: string
                  maxLength: 100
                logo_uri:
                  type: string
                primary_color:
                  type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                  role:
                    type: string
                  message:
                    type: string
          description: Organization created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid slug/name
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization self-service disabled (open_platform.enabled)
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Slug taken or org quota exceeded
      security:
      - bearerAuth: []
      summary: Create Organization (self-service)
      tags:
      - Organization
  /api/me/organizations/{slug}/invitations:
    get:
      description: List pending (unaccepted) invitations (org owner/admin).
      operationId: get_api_me_organizations_{slug}_invitations
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  invitations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        email:
                          type: string
                        role:
                          type: string
                        expires_at:
                          type: string
                  total:
                    type: integer
          description: Pending invitations
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Owner or admin role required
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization not found
      security:
      - bearerAuth: []
      summary: List Pending Invitations
      tags:
      - Organization
    post:
      description: Create a single-use 72h invitation (org owner/admin). The
        token is returned once and must be delivered out-of-band; email
        delivery is not part of v1.4.0.
      operationId: post_api_me_organizations_{slug}_invitations
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                role:
                  type: string
                  enum: [member, admin]
                  default: member
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  email:
                    type: string
                  role:
                    type: string
                  token:
                    type: string
                    description: Present exactly once; also delivered by
                      email when SMTP is configured.
                  expires_at:
                    type: string
                  message:
                    type: string
          description: Invitation created (token present once)
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid email or role
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Owner or admin role required
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: A pending invitation for this email already exists, or the pending-invitation cap was reached
      security:
      - bearerAuth: []
      summary: Invite Organization Member
      tags:
      - Organization
  /api/me/organizations/{slug}/consents:
    get:
      description: Active organization consents grouped by client, each scope
        with its own granted_by / granted_at (org owner/admin; v1.4.0 M2).
        Members of the org skip the personal consent prompt for scopes
        covered by these rows.
      operationId: get_api_me_organizations_{slug}_consents
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                  consents:
                    type: array
                    items:
                      type: object
                      properties:
                        client_id:
                          type: string
                        scopes:
                          type: array
                          items:
                            type: object
                            properties:
                              scope:
                                type: string
                              granted_by:
                                type: integer
                              granted_at:
                                type: string
                  total:
                    type: integer
          description: Active org consents grouped by client
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Owner or admin role required
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization not found
      security:
      - bearerAuth: []
      summary: List Organization Consents
      tags:
      - Organization
  /api/me/organizations/{slug}/consents/{clientId}:
    delete:
      description: 'Revoke every active consent of the (org, client) pair (org
        owner/admin). Revocation only affects FUTURE authorizations; issued
        tokens are not revoked (O4). 404 when no active rows remain.'
      operationId: delete_api_me_organizations_{slug}_consents_{clientId}
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      - description: Client identifier whose org consents are revoked
        in: path
        name: clientId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                  client_id:
                    type: string
                  revoked:
                    type: integer
                  message:
                    type: string
          description: Consents revoked (future authorizations only)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Owner or admin role required
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization not found, or no active consents for this client
      security:
      - bearerAuth: []
      summary: Revoke Organization Consents
      tags:
      - Organization
  /api/me/organizations/{slug}/consent-requests:
    post:
      description: 'A member asks the org managers to grant an organization consent
        for an application (body {client_id}; #236 plan B). Idempotent: re-filing
        with an identical pending request returns 200 with the existing row. 404
        for unknown clients, 409 when the client is already org-owned or already
        consented.'
      operationId: post_api_me_organizations_{slug}_consent-requests
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - client_id
              properties:
                client_id:
                  type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  organization_id:
                    type: integer
                  client_id:
                    type: string
                  requested_by:
                    type: integer
                  requested_at:
                    type: string
                  status:
                    type: string
                  message:
                    type: string
          description: Request filed, or an identical pending request already exists
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid input (client_id required)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Caller is not a member of this organization
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization or application not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Application already org-owned or already consented
      security:
      - bearerAuth: []
      summary: File Organization Consent Request
      tags:
      - Organization
    get:
      description: Every pending consent request of the organization with requester
        names (org owner/admin; #236 plan B).
      operationId: get_api_me_organizations_{slug}_consent-requests
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                  requests:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        organization_id:
                          type: integer
                        client_id:
                          type: string
                        requested_by:
                          type: integer
                        requester_username:
                          type: string
                        requested_at:
                          type: string
                        status:
                          type: string
                  total:
                    type: integer
          description: Pending consent requests of the organization
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Owner or admin role required
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization not found
      security:
      - bearerAuth: []
      summary: List Pending Consent Requests
      tags:
      - Organization
  /api/me/organizations/{slug}/consent-requests/{requestId}/approve:
    post:
      description: 'Approve a pending request (org owner/admin): one
        organization_consents row per scope of the client''s registered set is
        written and sibling pending requests for the same (org, client) are
        auto-approved. Idempotent on already-approved rows; 409 on rejected rows.'
      operationId: post_api_me_organizations_{slug}_consent-requests_{requestId}_approve
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      - description: Consent request id
        in: path
        name: requestId
        required: true
        schema:
          type: integer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  client_id:
                    type: string
                  status:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
                  message:
                    type: string
          description: Consent request approved and consent rows written
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid request id
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Owner or admin role required
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization or request not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Request was rejected
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Failed to write the organization consent rows
      security:
      - bearerAuth: []
      summary: Approve Consent Request
      tags:
      - Organization
  /api/me/organizations/{slug}/consent-requests/{requestId}/reject:
    post:
      description: 'Reject a pending request (org owner/admin); optional body
        {reason}. Does not cascade to sibling requests; the member may re-file.'
      operationId: post_api_me_organizations_{slug}_consent-requests_{requestId}_reject
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      - description: Consent request id
        in: path
        name: requestId
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  client_id:
                    type: string
                  status:
                    type: string
                  message:
                    type: string
          description: Consent request rejected
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid request id
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Owner or admin role required
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization or request not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Request is already decided
      security:
      - bearerAuth: []
      summary: Reject Consent Request
      tags:
      - Organization
  /api/me/organizations/{slug}/consent-requests/{requestId}:
    delete:
      description: The requester withdraws their OWN pending request (#236 plan
        B). Any other id resolves to the same 404 (anti-enumeration).
      operationId: delete_api_me_organizations_{slug}_consent-requests_{requestId}
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      - description: Consent request id
        in: path
        name: requestId
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  status:
                    type: string
                  message:
                    type: string
          description: Consent request withdrawn
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid request id
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Caller is not a member of this organization
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization not found, or the request is not the caller's pending request
      security:
      - bearerAuth: []
      summary: Withdraw Consent Request
      tags:
      - Organization
  /api/me/organizations/{slug}/successor-nomination:
    post:
      description: 'The organization owner nominates a successor (any live user,
        may be a non-member). Replaces any previous pending nomination (idempotent);
        the nominee must accept before the seat moves (v1.4.0 M3).'
      operationId: post_api_me_organizations_{slug}_successor-nomination
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id]
              properties:
                user_id:
                  type: integer
                  format: int64
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                  nominee_user_id:
                    type: integer
                  message:
                    type: string
          description: Nomination recorded (pending the nominee's acceptance)
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid body
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Only the organization owner may nominate
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization or target user not found
      security:
      - bearerAuth: []
      summary: Nominate Successor
      tags:
      - Organization
    delete:
      description: The organization owner withdraws the pending successor
        nomination (404 when none is pending).
      operationId: delete_api_me_organizations_{slug}_successor-nomination
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                  message:
                    type: string
          description: Nomination withdrawn
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Only the organization owner may withdraw
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization not found, or no pending nomination
      security:
      - bearerAuth: []
      summary: Withdraw Successor Nomination
      tags:
      - Organization
  /api/me/organizations/{slug}/successor-nomination/accept:
    post:
      description: 'The nominated successor accepts. The seat swap is one
        transaction: the nominee''s membership becomes owner, every other owner
        row demotes to admin, and the nomination is marked accepted (all or
        nothing).'
      operationId: post_api_me_organizations_{slug}_successor-nomination_accept
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                  owner_user_id:
                    type: integer
                  message:
                    type: string
          description: Ownership transferred
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Only the nominated successor may accept
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization not found, or no pending nomination
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Succession no longer pending or the swap failed; retry
      security:
      - bearerAuth: []
      summary: Accept Succession
      tags:
      - Organization
  /api/me/organizations/{slug}/invitations/{invitationId}:
    delete:
      description: Revoke a pending invitation (org owner/admin).
      operationId: delete_api_me_organizations_{slug}_invitations_{invitationId}
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      - description: Invitation ID
        in: path
        name: invitationId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                    message:
                      type: string
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid invitation id
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Owner or admin role required
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invitation not found
      security:
      - bearerAuth: []
      summary: Revoke Invitation
      tags:
      - Organization
  /api/me/organizations/{slug}/members:
    get:
      description: List members of an organization (any member may view).
      operationId: get_api_me_organizations_{slug}_members
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      type: object
                      properties:
                        user_id:
                          type: integer
                        username:
                          type: string
                        display_name:
                          type: string
                        role:
                          type: string
                          enum: [owner, admin, member]
                  total:
                    type: integer
          description: Members list
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Not a member of this organization
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization not found
      security:
      - bearerAuth: []
      summary: List Organization Members
      tags:
      - Organization
  /api/me/organizations/{slug}/members/{userId}:
    delete:
      description: Remove a member. Owner removes anyone except self; admins
        remove members only; members may only remove themselves (leave). The
        owner seat cannot be removed.
      operationId: delete_api_me_organizations_{slug}_members_{userId}
      parameters:
      - description: Organization slug
        in: path
        name: slug
        required: true
        schema:
          type: string
      - description: Internal user ID
        in: path
        name: userId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                    message:
                      type: string
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid user id
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Insufficient role for this removal / owner seat is irremovable
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Organization or membership not found
      security:
      - bearerAuth: []
      summary: Remove Organization Member
      tags:
      - Organization
  /api/me/password:
    put:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Change the current user's password. A successful change also
        clears the must_change_password flag (#145) and revokes all existing
        tokens. For the forced first-login flow (no Bearer token available) use
        POST /oauth2/password/change instead.
      operationId: put_api_me_password
      responses:
        '200':
          description: Password changed successfully
        '400':
          description: Invalid request body
        '401':
          description: Unauthorized or current password incorrect
        '404':
          description: User not found
      security:
      - bearerAuth: []
      summary: Change Password
      tags:
      - User Profile
  /api/me/profile:
    patch:
      description: Update the current user's editable profile fields (v1.4.0
        profile minimal set). Body keys are optional; an absent key leaves the
        field unchanged, an empty string clears it. display_name is trimmed
        and capped at 100 code points without control characters; avatar_url
        must be an https URL of at most 2048 chars (served verbatim, never
        fetched server-side).
      operationId: patch_api_me_profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                display_name:
                  type: string
                  maxLength: 100
                avatar_url:
                  type: string
                  maxLength: 2048
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
          description: Profile updated
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid input
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: User not found
      security:
      - bearerAuth: []
      summary: Update User Profile
      tags:
      - User Profile
  /api/me/social/links:
    get:
      description: List the social provider identities (github/google/wechat)
        linked to the current user. The seeded password-subject mapping
        (provider=local) is not a social identity and is excluded. Requires
        the `profile` scope.
      operationId: get_api_me_social_links
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialLinksList'
          description: Linked social identities
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing/invalid Bearer token
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: User not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Social linking not configured or repository failure
      security:
      - bearerAuth: []
      summary: List Linked Social Accounts
      tags:
      - User Profile
  /api/me/social/links/{provider}/authorize:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: 'Begin a social link flow (#71): mint a one-time state
        bound to (current user, provider) and return the provider authorize
        URL (with the state embedded) the SPA must redirect to. The link-back
        POST must present the same state; tokens are single-use with a short
        TTL. Fails closed (500) when linking or the state store (Redis) is
        not configured. Requires the `profile` scope.'
      operationId: post_api_me_social_links_provider_authorize
      parameters:
      - description: Social provider name
        in: path
        name: provider
        required: true
        schema:
          type: string
          enum: [github, google, wechat]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  provider:
                    type: string
                  state:
                    type: string
                  authorize_url:
                    type: string
          description: One-time state minted; authorize_url to redirect to
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unsupported provider
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing/invalid Bearer token
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Linking or state store not configured; provider not configured
      security:
      - bearerAuth: []
      summary: Begin Social Link (mint one-time state)
      tags:
      - User Profile
  /api/me/social/links/{provider}:
    delete:
      description: Remove the current user's linked identity for a provider.
        Existing sessions issued through that provider are NOT revoked --
        they stay valid until natural expiry. The provider identity cannot
        be used for new sign-ins until it is linked to an account again.
        Refused with 409 when it is the user's last social link and the user
        has no usable password (last-credential guard). Requires the
        `profile` scope.
      operationId: delete_api_me_social_links_provider
      parameters:
      - description: Social provider name
        in: path
        name: provider
        required: true
        schema:
          type: string
          enum: [github, google, wechat]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialLinkResult'
          description: Social account unlinked successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unsupported provider
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing/invalid Bearer token
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: No linked account for this provider
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Last-credential guard refused the unlink
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Repository failure
      security:
      - bearerAuth: []
      summary: Unlink Social Account
      tags:
      - User Profile
    post:
      description: Verify a provider authorization code (the SPA completes
        the provider redirect and submits the code) and link that provider
        identity to the current user. Conflicts (409) when the identity is
        already linked to any account or the user already has a different
        mapping for the provider. Requires the `profile` scope.
      operationId: post_api_me_social_links_provider
      parameters:
      - description: Social provider name
        in: path
        name: provider
        required: true
        schema:
          type: string
          enum: [github, google, wechat]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code, state]
              properties:
                code:
                  type: string
                  description: Authorization code from the provider's OAuth2
                    callback.
                state:
                  type: string
                  description: The one-time state token from the authorize
                    step (single use, bound to this user and provider).
                    Unknown/expired/replayed or foreign-bound states are
                    rejected with 400 before any provider call (#71).
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialLinkResult'
          description: Social account linked successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unsupported provider, missing code/state, invalid or
            expired link state, or provider rejected the code
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing/invalid Bearer token
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: User not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Provider identity already linked
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Social linking not configured or repository failure
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Failed to contact the provider API
      security:
      - bearerAuth: []
      summary: Link Social Account
      tags:
      - User Profile
  /api/me/webauthn/credentials:
    get:
      description: List registered WebAuthn credentials.
      operationId: get_api_me_webauthn_credentials
      responses:
        '200':
          description: WebAuthn credentials list
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: List WebAuthn Credentials
      tags:
      - WebAuthn
  /api/me/webauthn/credentials/{credentialId}:
    delete:
      description: 'Remove a registered passkey (P0-7). The delete is
        ownership-scoped (the credential must belong to the Bearer subject);
        a foreign or unknown credential id answers the same generic 404.
        Deleting the last credential is allowed — WebAuthn and TOTP are
        parallel second factors.'
      operationId: delete_api_me_webauthn_credentials_credentialId
      parameters:
      - name: credentialId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Passkey deleted
        '401':
          description: Unauthorized
        '404':
          description: Credential not found (or not owned by the caller)
      security:
      - bearerAuth: []
      summary: Delete WebAuthn Credential
      tags:
      - WebAuthn
  /api/me/profile/custom-attributes:
    get:
      description: 'P1-3 (#280): the caller''s custom-attributes document
        (claims-mapping source data). Memory deployments answer 404.'
      operationId: get_api_me_profile_custom_attributes
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  custom_attributes:
                    type: object
          description: The attribute document
      security:
      - bearerAuth: []
      summary: Get Custom Attributes
      tags:
      - Me
    put:
      description: 'P1-3 (#280): FULL-REPLACE the custom-attributes document.
        Validation: JSON object, depth <= 2, serialized <= 8 KiB, keys
        ^[a-z][a-z0-9_]{0,63}$, prototype-pollution keys rejected
        (CUSTOM_ATTRIBUTES_INVALID).'
      operationId: put_api_me_profile_custom_attributes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Document updated
        '400':
          description: CUSTOM_ATTRIBUTES_INVALID
      security:
      - bearerAuth: []
      summary: Replace Custom Attributes
      tags:
      - Me
  /api/me/webauthn/register/begin:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: 'Start passkey registration (#142): ES256-only pubKeyCredParams,
        userVerification=required, user.id is the base64url of the internal
        user id bytes, excludeCredentials lists already-registered credentials,
        and the challenge is bound to the Bearer subject (no session cookie
        contract). Requires webauthn.rp_origins to be configured.'
      operationId: post_api_me_webauthn_register_begin
      responses:
        '200':
          description: WebAuthn registration options
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: WebAuthn Register Begin
      tags:
      - WebAuthn
  /api/me/webauthn/register/finish:
    post:
      description: 'Finish passkey registration (#142): the browser PublicKeyCredential
        is verified server-side (subject-bound challenge, origin allowlist,
        none-format attestation, ES256 COSE key) before anything is stored;
        the legacy {credential_id, public_key} body is rejected.'
      operationId: post_api_me_webauthn_register_finish
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebAuthnRegistrationCredential'
        required: true
      responses:
        '201':
          description: Passkey registered successfully
        '400':
          description: Invalid request or failed verification (WEBAUTHN_INVALID_ATTESTATION
            / WEBAUTHN_CHALLENGE_MISMATCH)
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: WebAuthn Register Finish
      tags:
      - WebAuthn
  /api/password-reset/confirm:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Confirm a password reset using the token sent via email.
      operationId: post_api_password-reset_confirm
      responses:
        '200':
          description: Password reset successful
        '400':
          description: Invalid or expired token
      summary: Confirm Password Reset
      tags:
      - User Verification
  /api/password-reset/request:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Request a password reset link to be sent via email.
      operationId: post_api_password-reset_request
      responses:
        '200':
          description: Reset link sent if the email exists
        '400':
          description: Invalid request
      summary: Request Password Reset
      tags:
      - User Verification
  /api/register:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Registers a new user account into the system.
      operationId: post_api_register
      parameters:
      - description: Desired username (required)
        in: query
        name: username
        required: true
        schema:
          type: string
      - description: Strong password (required)
        in: query
        name: password
        required: true
        schema:
          minLength: 8
          type: string
      - description: Email address (optional)
        in: query
        name: email
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                message: User registered successfully
                status: success
          description: User registered successfully
        '400':
          description: Invalid registration data
      summary: Register new user
      tags:
      - User
      - Registration
  /api/verify-email:
    get:
      description: Verify an email address using a token.
      operationId: get_api_verify-email
      responses:
        '200':
          description: Email verified successfully
        '400':
          description: Invalid or expired token
      summary: Verify Email
      tags:
      - User Verification
  /api/verify-email/resend:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Resend the email verification link.
      operationId: post_api_verify-email_resend
      responses:
        '200':
          description: Verification email sent
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '404':
          description: User not found
      summary: Resend Verification Email
      tags:
      - User Verification
  /api/verify-email/resend-by-email:
    post:
      description: "Resend the email verification link, identifying the account by email address. Unauthenticated (see issue 198): a self-registered user holds no token yet. Rate-limited per (ip, email) with an identical response for unknown, already-verified, and emailed addresses (anti-enumeration)."
      operationId: post_api_verify-email_resend-by-email
      requestBody:
        content:
          application/json:
            schema:
              properties:
                email:
                  type: string
              required:
              - email
              type: object
      responses:
        '200':
          description: Verification email sent if the email exists and is unverified
        '400':
          description: Invalid request
        '429':
          description: Rate limited
      summary: Resend Verification Email (by email address)
      tags:
      - User Verification
  /api/wechat/login:
    post:
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Optional empty body (action-style operation).
      description: Exchange WeChat authorization code for user information. This endpoint
        handles the server-side OAuth2 flow with WeChat Open Platform.
      operationId: post_api_wechat_login
      parameters:
      - description: Authorization code from WeChat OAuth2 callback (required)
        in: query
        name: code
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                access_token: eyJhbGciOi...
                expires_in: 3600
                refresh_token: eyJhbGciOi...
                token_type: Bearer
              schema:
                $ref: '#/components/schemas/SocialLoginTokenResponse'
          description: First-party token pair issued for the WeChat-linked local account (the pre-#70 profile-only object is still returned when the service runs without an account repository - degraded mode, not the deployed configuration)
        '400':
          content:
            application/json:
              example:
                error: Missing code parameter
          description: Invalid request (missing or invalid code)
        '403':
          description: Provider identity is not linked to a local account and first-login auto-create is disabled (AUTH_SOCIAL_ACCOUNT_NOT_LINKED)
        '502':
          description: Failed to contact WeChat API
      summary: WeChat OAuth2 Login
      tags:
      - External Auth
      - WeChat
  /health:
    get:
      description: Aggregate health status of the service (process + database).
      operationId: get_health
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
          description: Service is healthy (or partially — inspect status field)
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
          description: Service unhealthy
      summary: Health check
      tags:
      - System
  /health/live:
    get:
      description: Liveness probe — always 200 while the process is up (no dependency
        checks).
      operationId: get_health_live
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
          description: Service is alive
      summary: Liveness probe
      tags:
      - System
  /health/ready:
    get:
      description: Readiness probe — database / redis dependency checks; 503 when a
        required dependency is down.
      operationId: get_health_ready
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
          description: Service is ready
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
          description: Service degraded or unhealthy (inspect status/database/redis)
      summary: Readiness probe
      tags:
      - System
  /oauth2/authorize:
    get:
      description: 'OAuth2 authorization endpoint - initiates authorization flow.
        Sessions paused at the MFA challenge or flagged must_change_password
        (#144/#145) are treated as not fully authenticated: prompt=none answers
        error=login_required, silent requests are redirected to the login /
        password-change page instead of issuing a code.'
      operationId: get_oauth2_authorize
      parameters:
      - description: Client identifier (required)
        in: query
        name: client_id
        required: true
        schema:
          type: string
      - description: Redirect URI (required)
        in: query
        name: redirect_uri
        required: true
        schema:
          type: string
      - description: Response type, must be 'code' (required)
        in: query
        name: response_type
        required: true
        schema:
          type: string
      - description: Requested scope (optional)
        in: query
        name: scope
        required: false
        schema:
          type: string
      - description: Opaque value to maintain state between request and callback (recommended)
        in: query
        name: state
        required: false
        schema:
          type: string
      - description: PKCE code challenge (RFC 7636). Required for public clients
          when auth.require_pkce_for_public is enabled (default true).
        in: query
        name: code_challenge
        required: false
        schema:
          type: string
      - description: PKCE code challenge method ('plain' or 'S256')
        in: query
        name: code_challenge_method
        required: false
        schema:
          type: string
      - description: OIDC nonce (anti-replay). Echoed in the id_token when openid
          scope is requested.
        in: query
        name: nonce
        required: false
        schema:
          type: string
      - description: 'OIDC prompt values, space-separated (none|login|consent).
          none forbids UI; login forces re-auth; consent forces the consent
          screen. Combining none with another value returns 400. (OIDC Core
          §3.1.2.1)'
        in: query
        name: prompt
        required: false
        schema:
          type: string
      - description: Maximum allowable age in seconds of the user's authentication.
          If the session auth_time is older, re-authentication is forced.
        in: query
        name: max_age
        required: false
        schema:
          type: integer
      - description: 'Organization context hint (v1.4.0): integer id or slug
          of the organization this authorization is made in. Accepted only
          when the user is a current member and the client belongs to that
          organization; every rejection renders the same inline 400 (no
          redirect). Combine with the org scope to receive org_ctx claims.'
        in: query
        name: org_id
        required: false
        schema:
          type: string
      responses:
        '302':
          description: Redirect to client with authorization code (or an error=
            redirect for prompt=none / invalid_scope / etc.)
        '400':
          description: Invalid request (malformed prompt, missing required
            params, or an invalid/unauthorized org_id)
      summary: Request authorization
      tags:
      - OAuth2
      - Authorization
  /oauth2/consent:
    post:
      description: Submit user consent for requested scopes. Redirects back to client.
      operationId: post_oauth2_consent
      parameters:
      - description: Client identifier (required)
        in: query
        name: client_id
        required: true
        schema:
          type: string
      - description: User identifier (required)
        in: query
        name: user_id
        required: true
        schema:
          type: string
      - description: Requested scope to consent (required)
        in: query
        name: scope
        required: true
        schema:
          type: string
      - description: Redirect URI (required)
        in: query
        name: redirect_uri
        required: true
        schema:
          type: string
      - description: Opaque value to maintain state
        in: query
        name: state
        required: false
        schema:
          type: string
      - description: 'Action to perform: ''approve'' or ''deny'' (required)'
        in: query
        name: action
        required: true
        schema:
          enum:
          - approve
          - deny
          type: string
      - description: Server-minted one-shot CSRF nonce from the authorize->consent redirect (required; consumed on use)
        in: query
        name: consent_csrf
        required: true
        schema:
          type: string
      responses:
        '302':
          description: Redirect to client with authorization code or error
        '400':
          description: Missing/expired/mismatched consent_csrf nonce, or (deny) redirect_uri not registered for the client (VALIDATION_INVALID_INPUT / VALIDATION_REDIRECT_URI_NOT_REGISTERED)
        '401':
          description: 'No authenticated session (AUTH_SESSION_REQUIRED), or the
            session is paused at the MFA challenge (AUTH_MFA_REQUIRED, #144:
            consent must not be granted on amr="pwd" for an MFA-required account)'
        '403':
          description: 'user_id does not match the authenticated session
            (AUTHZ_ACCESS_DENIED), or the account is flagged must_change_password
            (AUTH_PASSWORD_CHANGE_REQUIRED, #145)'
      summary: Submit user consent
      tags:
      - OAuth2
      - Consent
  /oauth2/authorize-context:
    get:
      description: 'Public application-name discovery for the login/consent
        screens (P0-6): answers {client_name} for active clients, so the user
        sees WHICH application is asking for credentials before typing a
        password. Unknown or soft-deleted clients answer 404; every other
        failure degrades to {client_name: <client_id>}. P1-1 (#279) extends
        the payload additively with the client''s logo_uri (V041, https-only
        at write time) and, for org-owned applications, the owning
        organization''s brand block {org_name, logo_uri?, primary_color?}.
        Branding is display-only and untrusted — the consent screen pairs it
        with the owner attribution label. client_id is not a secret (it
        appears in every authorize redirect).'
      operationId: get_oauth2_authorize_context
      parameters:
      - name: client_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Application display name + branding
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_name:
                    type: string
                  logo_uri:
                    type: string
                    description: Client brand image (absent when unset)
                  org:
                    nullable: true
                    type: object
                    properties:
                      org_name:
                        type: string
                      logo_uri:
                        type: string
                      primary_color:
                        type: string
        '400':
          description: Missing client_id
        '404':
          description: Unknown or soft-deleted client
      summary: Authorize Context (client display name + branding)
      tags:
      - OAuth2
  /oauth2/consent/context:
    get:
      description: >-
        Server-side consent-screen context (v1.4.0 M1b, #223 second half):
        the owner attribution label and the organization-membership banner
        for the consent flow whose server-minted consent_csrf nonce is
        presented. The nonce is validated but NOT consumed (the one-shot
        consume stays with POST /oauth2/consent). The (client_id,
        redirect_uri) pair must be registered, mirroring what reaching the
        consent screen via authorize already requires; the org block comes
        from the binding stashed server-side at authorize time (unknown or
        missing state, or a flow without an org context, yields org=null).
      operationId: get_oauth2_consent_context
      parameters:
      - description: Server-minted one-shot CSRF nonce from the authorize->consent redirect (required; validated, not consumed)
        in: query
        name: consent_csrf
        required: true
        schema:
          type: string
      - description: The client the consent flow is for (required)
        in: query
        name: client_id
        required: true
        schema:
          type: string
      - description: The flow's redirect_uri; must be registered for client_id (required)
        in: query
        name: redirect_uri
        required: true
        schema:
          type: string
      - description: The flow's state value; resolves the server-stashed org binding (no binding or unknown state -> org is null)
        in: query
        name: state
        required: false
        schema:
          type: string
      - description: The session user id echoed from the consent URL (required; must match the session)
        in: query
        name: user_id
        required: true
        schema:
          type: string
      - description: 'P1-1 (#279): the flow''s requested scopes (space- or
          comma-separated); when present, the response carries localized
          descriptions per scope from the oauth2_scopes catalog'
        in: query
        name: scope
        required: false
        schema:
          type: string
      - description: 'P1-1 (#279): page locale (a "zh*" prefix selects the
          zh-CN description column; anything else selects the en column)'
        in: query
        name: locale
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  owner_name:
                    type: string
                    description: 'Attribution label: org name for org apps, the
                      creator''s display name for personal apps; empty for
                      admin-seeded clients and on storage degradation.'
                  client_name:
                    type: string
                    description: 'P1-1: the client''s display name (falls back
                      to the client_id).'
                  logo_uri:
                    type: string
                    description: 'P1-1: the client''s brand image (absent when
                      unset).'
                  scope_descriptions:
                    type: array
                    description: 'P1-1: localized descriptions for the scopes
                      named in the `scope` parameter (unknown names omitted;
                      the frontend dictionary is the missing-key fallback).'
                    items:
                      type: object
                      properties:
                        scope:
                          type: string
                        description_i18n:
                          type: string
                  org:
                    nullable: true
                    type: object
                    properties:
                      org_id:
                        type: integer
                      org_name:
                        type: string
                      logo_uri:
                        type: string
                      primary_color:
                        type: string
                    description: The org context this flow is authorizing
                      under (design 2.1); null when the flow has no org
                      binding. P1-1 adds the org brand fields (absent when
                      unset).
          description: Consent context (owner_name empty for admin-seeded clients; org null for flows without an org binding)
        '400':
          description: Missing/unknown/expired consent_csrf, missing client_id/redirect_uri, or redirect_uri not registered for client_id (VALIDATION_INVALID_INPUT / VALIDATION_REDIRECT_URI_NOT_REGISTERED)
        '401':
          description: No authenticated session (AUTH_SESSION_REQUIRED)
        '403':
          description: user_id does not match the authenticated session (AUTHZ_ACCESS_DENIED)
      summary: Consent screen context (owner attribution + org banner)
      tags:
      - OAuth2
      - Consent
  /oauth2/device/approve:
    post:
      description: >-
        Admin-only approval of a pending device authorization (RFC 8628 user
        approval step). Requires an admin Bearer token (AuthorizationFilter).
      operationId: post_oauth2_device_approve
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - user_code
              - user_id
              properties:
                user_code:
                  type: string
                  description: The user_code shown to the user by the device.
                user_id:
                  type: string
                  description: Approving user's identifier.
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: approved
                  user_code:
                    type: string
          description: Device authorization approved
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing user_code/user_id, or the code is invalid/already processed/expired
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing/invalid Bearer token
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Insufficient permissions (admin role / scope required)
      security:
      - bearerAuth: []
      summary: Approve Device Authorization
      tags:
      - OAuth2
      - Device Flow
  /oauth2/device_authorization:
    post:
      description: 'RFC 8628 device authorization endpoint. A CONFIDENTIAL client
        authenticates with client_secret (HTTP Basic preferred); a PUBLIC client
        sends client_id only. The user then visits verification_uri and an admin
        approves via /oauth2/device/approve; the device polls /oauth2/token with
        grant_type=urn:ietf:params:oauth:grant-type:device_code.'
      operationId: post_oauth2_device_authorization
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - client_id
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
                  description: Required for CONFIDENTIAL clients (send via HTTP Basic when possible).
                scope:
                  type: string
                  description: Space-separated requested scopes (optional).
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAuthorizationResponse'
          description: Device authorization response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: invalid_request (missing client_id)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: invalid_client (unknown client / bad secret)
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: server_error
      summary: Device Authorization
      tags:
      - OAuth2
      - Device Flow
  /oauth2/end_session:
    get:
      description: 'OIDC RP-Initiated Logout 1.0 §2. Terminates the user''s server-side
        session and (optionally) redirects to a registered post_logout_redirect_uri.
        When id_token_hint is supplied it MUST pass end-to-end verification (#78:
        RS256 signature against the OP key set, strict alg/kid, iss, exp) — any
        failure, or a hint subject that contradicts the browser session, is
        rejected with 400 AUTH_INVALID_ID_TOKEN_HINT (Error Envelope). post_logout_redirect_uri
        MUST be registered for the client identifying itself in the request: the
        verified id_token_hint (its aud claim) or, when no hint is supplied, the
        client_id parameter (RP-Initiated Logout 1.0 §2.1 defines client_id for
        exactly this case, #88-3). With NEITHER hint nor client_id a redirect URI
        is rejected with 400. Accepts both GET (link-based) and POST
        (form-based).'
      operationId: get_oauth2_end_session
      parameters:
      - description: 'Previously issued id_token hinting at the client/session to
          terminate. Signature-verified against the OP key set (#78); a bad or
          expired signature, wrong issuer, or a subject contradicting the current
          session yields 400 AUTH_INVALID_ID_TOKEN_HINT. The aud claim (string or array,
          RFC 7519 §4.1.3) identifies the client(s) for validating
          post_logout_redirect_uri; the first candidate owning the URI wins.'
        in: query
        name: id_token_hint
        required: false
        schema:
          type: string
      - description: URI to redirect to after logout. Must be registered for the
          id_token_hint client; rejected with 400 otherwise.
        in: query
        name: post_logout_redirect_uri
        required: false
        schema:
          type: string
      - description: 'RP self-identification when id_token_hint is absent
          (RP-Initiated Logout 1.0 §2.1). The post_logout_redirect_uri must be
          registered for this client (#88-3).'
        in: query
        name: client_id
        required: false
        schema:
          type: string
      - description: Opaque value echoed back to the post_logout_redirect_uri.
        in: query
        name: state
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
          description: Logged out (no post_logout_redirect_uri supplied)
        '302':
          description: Redirect to the validated post_logout_redirect_uri (with state)
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: 'Error Envelope. (a) id_token_hint failed verification/expired/issuer
            mismatch/session-subject mismatch/aud without a usable client identifier:
            AUTH_INVALID_ID_TOKEN_HINT; (b) post_logout_redirect_uri supplied without an
            id_token_hint: AUTH_INVALID_ID_TOKEN_HINT; (c) post_logout_redirect_uri not
            registered for any aud client of the verified hint:
            VALIDATION_REDIRECT_URI_NOT_REGISTERED.'
      summary: RP-Initiated Logout
      tags:
      - OAuth2
      - OIDC
    post:
      description: 'OIDC RP-Initiated Logout (POST form-based variant; see GET for
        semantics). id_token_hint, when supplied, is signature-verified (#78);
        verification failure yields 400 AUTH_INVALID_ID_TOKEN_HINT Error Envelope.'
      operationId: post_oauth2_end_session
      parameters:
      - description: Previously issued id_token hint (signature-verified, #78).
        in: query
        name: id_token_hint
        required: false
        schema:
          type: string
      - description: 'RP self-identification when id_token_hint is absent
          (RP-Initiated Logout 1.0 §2.1). The post_logout_redirect_uri must be
          registered for this client (#88-3).'
        in: query
        name: client_id
        required: false
        schema:
          type: string
      - description: Registered post-logout redirect URI.
        in: query
        name: post_logout_redirect_uri
        required: false
        schema:
          type: string
      - description: Opaque state value.
        in: query
        name: state
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
          description: Logged out
        '302':
          description: Redirect to post_logout_redirect_uri
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: 'Error Envelope: id_token_hint verification failure, or neither
            id_token_hint nor client_id supplied with a post_logout_redirect_uri
            (AUTH_INVALID_ID_TOKEN_HINT), or post_logout_redirect_uri not registered
            for the identifying client (VALIDATION_REDIRECT_URI_NOT_REGISTERED).
            See GET for full semantics.'
      summary: RP-Initiated Logout (POST)
      tags:
      - OAuth2
      - OIDC
  /oauth2/introspect:
    post:
      description: RFC 7662 OAuth 2.0 Token Introspection. Returns information about
        a token. The calling client MUST authenticate (HTTP Basic preferred;
        client_id/client_secret form parameters accepted).
      operationId: post_oauth2_introspect
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - token
              properties:
                token:
                  type: string
                  description: The string value of the token (required).
                token_type_hint:
                  type: string
                  description: 'Optional hint: access_token or refresh_token (accepted, currently ignored).'
                client_id:
                  type: string
                  description: Client identifier (alternative to HTTP Basic authentication).
                client_secret:
                  type: string
                  description: Client secret (alternative to HTTP Basic authentication).
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntrospectionResponse'
          description: 'Token status and metadata ({"active": false} for unknown/inactive tokens)'
          headers:
            Cache-Control:
              description: Always "no-store".
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: invalid_request (missing token)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: invalid_client (authentication failed / auth-method mismatch)
          headers:
            WWW-Authenticate:
              description: Basic realm challenge when HTTP Basic was attempted.
              schema:
                type: string
        '429':
          description: 'Too Many Requests -- F-018 rate limit tripped by repeated
            failed authentication/validation attempts for this (client_ip, client_id).
            Accompanied by a Retry-After header and an OAuth2-style {error:
            invalid_request, error_description} body.'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
      security:
      - clientCredentialsAuth: []
      summary: Introspect token
      tags:
      - OAuth2
      - Token
  /oauth2/login:
    post:
      description: Authenticates user credentials and generates an authorization code.
        Usually called by the frontend login page during the authorization code flow.
        Accepts a JSON body or form-encoded parameters; when MFA is enabled on the
        account the response defers to POST /oauth2/mfa/verify.
      operationId: post_oauth2_login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/LoginSuccessResponse'
                - $ref: '#/components/schemas/MfaRequiredResponse'
                - $ref: '#/components/schemas/PasswordChangeRequiredResponse'
              examples:
                success:
                  summary: Login succeeded (json=true)
                  value:
                    code: xyz123
                    location: http://127.0.0.1:5173/callback?code=xyz123&state=abc
                mfa_required:
                  summary: MFA challenge required
                  value:
                    mfa_required: true
                    mfa_token: '42'
                    message: MFA verification required. Submit TOTP code to /oauth2/mfa/verify
                password_change_required:
                  summary: Forced first-login password change (#145)
                  value:
                    password_change_required: true
                    message: Password change required. Change the password via
                      POST /oauth2/password/change before signing in
          description: 'Authentication outcome: authorization code issued (JSON with
            code/location when json=true), MFA challenge deferred, or a forced
            password-change request while the account is flagged
            must_change_password (bootstrap admin / admin-created users; no code
            is issued until the password is changed)'
        '302':
          description: Redirect with authorization code (browser flow / json omitted);
            PKCE-missing errors also redirect with ?error=... to a verified redirect_uri
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing username/password (VALIDATION_INVALID_INPUT)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Authentication failed (AUTH_INVALID_CREDENTIALS)
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Email not verified (AUTHZ_ACCESS_DENIED)
      summary: Authenticate user
      tags:
      - OAuth2
      - Authentication
  /oauth2/logout:
    post:
      description: Terminates the server-side session behind the presented Bearer
        access token (also fires OIDC back-channel logout notifications when
        configured).
      operationId: post_oauth2_logout
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
          description: Logged out successfully
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing/invalid Bearer token
      security:
      - bearerAuth: []
      summary: Logout
      tags:
      - OAuth2
      - Session
  /oauth2/mfa/verify:
    post:
      description: Verify MFA (TOTP) code during login. Completes the
        authorization-code issuance started by /oauth2/login when MFA was
        required. The PKCE code_verifier (C4, RFC 7636) must be supplied so
        the internally-generated code passes PKCE verification against the
        code_challenge persisted on the session during the first-factor
        login step. Accepts a JSON body or form-encoded parameters.
      operationId: post_oauth2_mfa_verify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MfaVerifyRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MfaVerifyRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/TokenResponse'
                - type: object
                  properties:
                    message:
                      type: string
                    mfa_verified:
                      type: boolean
          description: MFA verification successful — returns the token pair
            (access_token, refresh_token, id_token).
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid request (missing mfa_token/code, malformed TOTP)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid MFA code or client/redirect mismatch
      summary: Verify MFA Code (Login)
      tags:
      - MFA
  /oauth2/password/change:
    post:
      description: 'Changes the password of the session user while the account is
        flagged must_change_password (#145: bootstrap admin, admin-created users).
        Session-authenticated like /oauth2/login (no Bearer token — a flagged
        account cannot obtain tokens by design); requires old_password, applies
        the auth.min_password_length policy and a 128-character maximum, clears
        the flag, revokes all access/refresh tokens, and demotes the session to
        anonymous (sign in again). Only usable while the session carries the
        must_change_password marker set at login. JSON body only — the endpoint
        has no CSRF nonce of its own, so the content type (which a cross-site
        form cannot produce) plus the old_password knowledge factor close the
        cross-site surface.'
      operationId: post_oauth2_password_change
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - old_password
              - new_password
              properties:
                old_password:
                  type: string
                new_password:
                  type: string
                  description: Must satisfy auth.min_password_length (default 8)
                    and is capped at 128 characters.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
          description: Password changed; the must_change_password flag is cleared,
            all tokens revoked, and the session demoted to anonymous. Sign in
            again to continue.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: 'Non-JSON body (VALIDATION_INVALID_INPUT), missing fields
            (VALIDATION_MISSING_REQUIRED_FIELD), new password below the configured
            minimum (VALIDATION_PASSWORD_TOO_SHORT) or above 128 characters
            (VALIDATION_INVALID_INPUT)'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: 'No session / session without the must_change_password marker
            (AUTH_SESSION_REQUIRED), account locked (AUTH_INVALID_CREDENTIALS),
            or wrong old_password (AUTH_INVALID_CREDENTIALS)'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Database failure (DB_QUERY_ERROR)
      summary: Change Password (Forced First-Login Flow)
      tags:
      - Session
  /oauth2/register:
    post:
      description: "Dynamic client registration (admin-gated). Accepted
        metadata: client_name, client_type (CONFIDENTIAL|PUBLIC),
        token_endpoint_auth_method, redirect_uris (https enforced, loopback
        exempt), grant_types, and — P0-7b — optional
        post_logout_redirect_uris (dedicated RP-initiated-logout redirect
        registrations, same scheme policy; when registered they are
        authoritative for end_session's post_logout_redirect_uri
        validation)."
      operationId: post_oauth2_register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_name:
                  type: string
                client_type:
                  type: string
                  enum: [CONFIDENTIAL, PUBLIC]
                token_endpoint_auth_method:
                  type: string
                redirect_uris:
                  type: array
                  items:
                    type: string
                grant_types:
                  type: array
                  items:
                    type: string
                post_logout_redirect_uris:
                  type: array
                  items:
                    type: string
                  description: 'P0-7b: dedicated post-logout redirect
                    registrations (comma-joined at rest). Empty/unset: end_session
                    validates post_logout_redirect_uri against the login
                    redirect_uris (pre-v1.6.0 behavior).'
      responses:
        '201':
          description: Client registered successfully
        '400':
          description: Invalid client metadata
        '401':
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: Register Client
      tags:
      - OAuth2
      - Dynamic Registration
  /oauth2/revoke:
    post:
      description: "RFC 7009 OAuth 2.0 Token Revocation. Revokes an access OR
        refresh token (C3 fix — refresh tokens are now actually revoked, not
        silently no-op'd). The caller must be the token's owning client
        (ownership enforced via introspection). CONFIDENTIAL clients
        authenticate via client_secret (HTTP Basic or body); PUBLIC clients
        (token_endpoint_auth_method='none') authenticate with client_id only
        (RFC 7009 §2.1 exempts them from client authentication at this
        endpoint). Unknown or already-inactive tokens still return 200 per
        RFC 7009; the success body is EMPTY."
      operationId: post_oauth2_revoke
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - token
              properties:
                token:
                  type: string
                  description: The token that the client wants to get revoked (required).
                token_type_hint:
                  type: string
                  description: 'Optional hint: access_token or refresh_token (accepted, currently ignored).'
                client_id:
                  type: string
                  description: Client identifier (alternative to HTTP Basic authentication).
                client_secret:
                  type: string
                  description: Client secret (alternative to HTTP Basic; required for CONFIDENTIAL clients).
      responses:
        '200':
          description: Token revoked successfully or token did not exist (empty body)
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: invalid_request (missing token)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: invalid_client (authentication failed)
        '429':
          description: 'Too Many Requests -- F-018 rate limit tripped by repeated
            failed authentication/validation attempts for this (client_ip, client_id).
            Accompanied by a Retry-After header and an OAuth2-style {error:
            invalid_request, error_description} body.'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
      security:
      - clientCredentialsAuth: []
      - {}
      summary: Revoke token
      tags:
      - OAuth2
      - Token
  /oauth2/token:
    post:
      description: 'OAuth2 token endpoint - exchanges an authorization code,
        refresh token, client credentials, or device code for access tokens
        (RFC 6749 §3.2). Request parameters are sent as
        application/x-www-form-urlencoded (the server also accepts them as
        query parameters). Client authentication follows each client''s
        registered token_endpoint_auth_method (F-017): client_secret_basic
        (the default) -> HTTP Basic ONLY (a body client_secret is rejected);
        client_secret_post -> client_id + client_secret form fields ONLY (a
        Basic header is rejected); PUBLIC clients send client_id only (any
        client_secret is rejected).'
      operationId: post_oauth2_token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
          description: 'Token response with access_token and refresh_token. F-019
            (RFC 6749 §5.1): success responses carry Cache-Control: no-store and
            Pragma: no-cache and MUST NOT be cached.'
          headers:
            Cache-Control:
              description: Always "no-store" -- token responses MUST NOT be cached.
              schema:
                type: string
            Pragma:
              description: Always "no-cache" (HTTP/1.0 back-compat fallback).
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: >-
            invalid_request / invalid_grant / unsupported_grant_type /
            invalid_scope; device grant also returns authorization_pending,
            slow_down (plus non-standard interval field), expired_token, or
            access_denied here.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: invalid_client (authentication failed / forbidden secret on a PUBLIC client)
          headers:
            WWW-Authenticate:
              description: Basic realm challenge when HTTP Basic was attempted.
              schema:
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: 'Too Many Requests -- F-018 rate limit tripped by repeated
            failed authentication/validation attempts for this (client_ip, client_id),
            including device_code polling. Accompanied by a Retry-After header.'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
      summary: Exchange authorization code for access token
      tags:
      - OAuth2
      - Token
  /oauth2/userinfo:
    get:
      description: 'Returns information about the authenticated user. F-023 (OIDC
        Core §5.3): the access token''s scope MUST include openid; M2M tokens
        (client_credentials, subject client:*) are rejected. The response
        includes the email_verified claim (F-024) when an email is present.'
      operationId: get_oauth2_userinfo
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfoResponse'
          description: User information retrieved successfully
        '400':
          description: Invalid User ID format
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: 'Invalid/expired access token (invalid_token), or M2M token:
            client-credentials tokens have no user identity for userinfo'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2Error'
          description: 'insufficient_scope -- the access token lacks the openid scope
            (RFC 6750 §3; accompanied by WWW-Authenticate: Bearer error="insufficient_scope")'
        '404':
          content:
            application/json:
              example:
                error: User not found
          description: User not found
      security:
      - bearerAuth: []
      summary: Get user information
      tags:
      - OAuth2
      - User
  /oauth2/webauthn/authenticate/begin:
    post:
      description: 'Start passkey authentication (#142): the challenge is bound to
        the caller''s session (send cookies - credentials include); userVerification=required;
        ES256 only. Requires webauthn.rp_origins.'
      operationId: post_oauth2_webauthn_authenticate_begin
      responses:
        '200':
          description: WebAuthn authentication options
      summary: WebAuthn Authenticate Begin
      tags:
      - WebAuthn
  /oauth2/webauthn/authenticate/finish:
    post:
      description: 'Finish passkey authentication (#142): the session challenge is
        consumed unconditionally, the ES256 signature over authData || SHA256(clientDataJSON)
        is verified against the STORED COSE key, UV=1 is enforced and signCount
        regression is treated as cloning. On success a browser session is
        established (Set-Cookie). All failures answer the generic
        AUTH_INVALID_CREDENTIALS.'
      operationId: post_oauth2_webauthn_authenticate_finish
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebAuthnAssertionCredential'
        required: true
      responses:
        '200':
          description: WebAuthn authentication successful
        '400':
          description: Invalid request
        '401':
          description: Authentication failed (generic - credential, signature,
            challenge or policy)
      summary: WebAuthn Authenticate Finish
      tags:
      - WebAuthn
servers:
- description: Default server (relative path)
  url: /