auth-framework 0.5.0-rc19

# OAuth 2.0 Advanced and Auxiliary Endpoints

introspect:
    post:
        tags:
            - OAuth
        summary: Introspect a token
        description: Requires client authentication via HTTP Basic auth or request-body client credentials.
        operationId: introspectToken
        requestBody:
            required: true
            content:
                application/x-www-form-urlencoded:
                    schema:
                        $ref: "../schemas/oauth.yaml#/IntrospectTokenRequest"
        responses:
            "200":
                description: Introspection completed
                content:
                    application/json:
                        schema:
                            $ref: "../schemas/oauth.yaml#/TokenIntrospectionResponse"
            "400":
                $ref: "../components/responses.yaml#/BadRequest"
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"

par:
    post:
        tags:
            - OAuth
        summary: Submit a pushed authorization request
        operationId: pushedAuthorizationRequest
        requestBody:
            required: true
            content:
                application/x-www-form-urlencoded:
                    schema:
                        type: object
                        required:
                            - response_type
                            - client_id
                            - redirect_uri
                        properties:
                            response_type:
                                type: string
                                example: "code"
                            client_id:
                                type: string
                                example: "client_123"
                            redirect_uri:
                                type: string
                                format: uri
                                example: "https://client.example.com/callback"
                            scope:
                                type: string
                                example: "openid profile email"
                            state:
                                type: string
                                example: "xyz123"
                            nonce:
                                type: string
                                example: "nonce123"
                            code_challenge:
                                type: string
                            code_challenge_method:
                                type: string
        responses:
            "201":
                description: Request pushed successfully
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                request_uri:
                                    type: string
                                    example: "urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14eY22c"
                                expires_in:
                                    type: integer
                                    example: 90
                            required:
                                - request_uri
                                - expires_in
            "400":
                $ref: "../components/responses.yaml#/BadRequest"

device:
    post:
        tags:
            - OAuth
        summary: Initiate the device authorization helper flow
        description: The current server exposes device-code issuance at /oauth/device. The standard token polling companion route is not mounted separately; clients should treat this as a partial implementation.
        operationId: deviceAuthorization
        requestBody:
            required: true
            content:
                application/x-www-form-urlencoded:
                    schema:
                        type: object
                        required:
                            - client_id
                        properties:
                            client_id:
                                type: string
                                example: "client_123"
                            scope:
                                type: string
                                example: "openid profile email"
        responses:
            "200":
                description: Device code issued
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                device_code:
                                    type: string
                                    example: "dc_0123456789abcdef"
                                user_code:
                                    type: string
                                    example: "WDJBMJHT"
                                verification_uri:
                                    type: string
                                    example: "/device"
                                verification_uri_complete:
                                    type: string
                                    example: "/device?user_code=WDJBMJHT"
                                expires_in:
                                    type: integer
                                    example: 600
                                interval:
                                    type: integer
                                    example: 5
                            required:
                                - device_code
                                - user_code
                                - verification_uri
                                - verification_uri_complete
                                - expires_in
                                - interval
            "400":
                $ref: "../components/responses.yaml#/BadRequest"

ciba:
    post:
        tags:
            - OAuth
            - OpenID Connect
        summary: Initiate a backchannel authentication request
        description: The endpoint creates an auth_req_id and stores pending state. The REST token endpoint does not currently document a CIBA polling grant.
        operationId: cibaBackchannelAuth
        requestBody:
            required: true
            content:
                application/x-www-form-urlencoded:
                    schema:
                        type: object
                        properties:
                            client_id:
                                type: string
                                example: "client_123"
                            scope:
                                type: string
                                example: "openid"
                            login_hint:
                                type: string
                                example: "user@example.com"
                            login_hint_token:
                                type: string
                            id_token_hint:
                                type: string
                            binding_message:
                                type: string
                                example: "Approve sign-in"
        responses:
            "200":
                description: Backchannel authentication initiated
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                auth_req_id:
                                    type: string
                                    example: "5d1d18b8-6c1e-4d40-a2dd-1ef24f2c2938"
                                expires_in:
                                    type: integer
                                    example: 120
                                interval:
                                    type: integer
                                    example: 5
                            required:
                                - auth_req_id
                                - expires_in
                                - interval
            "400":
                $ref: "../components/responses.yaml#/BadRequest"

endSession:
    get:
        tags:
            - OpenID Connect
        summary: Perform RP-initiated logout
        operationId: endSession
        parameters:
            - name: id_token_hint
              in: query
              schema:
                  type: string
            - name: post_logout_redirect_uri
              in: query
              schema:
                  type: string
                  format: uri
            - name: state
              in: query
              schema:
                  type: string
        responses:
            "200":
                description: Logout completed without redirect
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                status:
                                    type: string
                                    example: "logged_out"
                            required:
                                - status
            "302":
                description: Redirect to the validated post_logout_redirect_uri

register:
    post:
        tags:
            - OAuth
        summary: Dynamically register a client
        description: Requires an admin bearer token or a configured initial access token.
        operationId: registerClient
        security:
            - bearerAuth: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        $ref: "../schemas/oauth.yaml#/ClientRegistrationRequest"
        responses:
            "201":
                description: Client registered successfully
                content:
                    application/json:
                        schema:
                            $ref: "../schemas/oauth.yaml#/ClientRegistrationResponse"
            "400":
                $ref: "../components/responses.yaml#/BadRequest"
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"

clientInfo:
    get:
        tags:
            - OAuth
        summary: Read stored client metadata
        operationId: getClientInfo
        parameters:
            - name: client_id
              in: path
              required: true
              schema:
                  type: string
              example: "client_123"
        responses:
            "200":
                description: Client metadata returned successfully
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: "../schemas/common.yaml#/ApiResponse"
                                - type: object
                                  properties:
                                      data:
                                          $ref: "../schemas/oauth.yaml#/ClientInfoResponse"
            "404":
                $ref: "../components/responses.yaml#/NotFound"