"/oauth/token":
    post:
        tags: [OAuth]
        operationId: oauthToken
        summary: OAuth 2.0 token endpoint
        description: |
            RFC 6749 token endpoint. Supports `authorization_code` and
            `refresh_token` grants. Authenticates via `client_id` +
            `client_secret` in the request body — does **not** use the
            Bigscreen `apiKey` bearer.

            Returns `501 endpoint_disabled` when
            `OAUTH_TOKEN_ENABLED` is not `true`.
        security: []
        requestBody:
            required: true
            content:
                application/x-www-form-urlencoded:
                    schema:
                        type: object
                        required: [grant_type, client_id, client_secret]
                        properties:
                            grant_type:
                                type: string
                                enum: [authorization_code, refresh_token]
                            client_id: { type: string }
                            client_secret: { type: string }
                            code:
                                type: string
                                description: Authorization code, when `grant_type=authorization_code`.
                            redirect_uri:
                                type: string
                                format: uri
                                description: Original redirect URI, when `grant_type=authorization_code`.
                            refresh_token:
                                type: string
                                description: Refresh token, when `grant_type=refresh_token`.
                            scope:
                                type: string
                                description: Space-separated scope subset request (refresh_token grant).
        responses:
            "200":
                description: Granted token bundle.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/OAuthTokenResponse.yaml" }
            "400":
                description: Invalid grant / missing parameters.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/OAuthError.yaml" }
            "401":
                description: Invalid `client_id` / `client_secret`.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/OAuthError.yaml" }
            "501":
                description: OAuth disabled (`OAUTH_TOKEN_ENABLED` is not `true`).
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/OAuthError.yaml" }

"/.well-known/jwks.json":
    get:
        tags: [OAuth]
        operationId: oauthJwks
        summary: JWKS — OAuth signing keys
        description: |
            RFC 7517 JWK Set — the public keys used to verify access /
            refresh tokens issued by `/oauth/token`. Returns `501` when
            OAuth is disabled.
        security: []
        responses:
            "200":
                description: JWK Set.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/JWKSResponse.yaml" }
            "501":
                description: OAuth disabled.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/OAuthError.yaml" }

"/.well-known/oauth-authorization-server":
    get:
        tags: [OAuth]
        operationId: oauthServerMetadata
        summary: OAuth authorization-server metadata
        description: |
            RFC 8414 authorization-server discovery document — describes
            the issuer, supported grant types, JWKS URI, and registered
            endpoints. Returns `501` when OAuth is disabled.
        security: []
        responses:
            "200":
                description: Discovery document.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/AuthorizationServerMetadata.yaml" }
            "501":
                description: OAuth disabled.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/OAuthError.yaml" }
