Bulk URL Checker OAuth API

openapi: 3.2.0
info:
  title: Reception Desk OAuth API
  description: API Gateway for URL Checker Engine
  version: 1.0.0
tags:
- name: OAuth
paths:
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - OAuth
      summary: Oauth Authorization Server Metadata
      description: RFC 8414 authorization server metadata document.
      operationId: oauth_authorization_server_metadata__well_known_oauth_authorization_server_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /oauth/register:
    post:
      tags:
      - OAuth
      summary: Register Client
      description: 'Public, unauthenticated endpoint. Every MCP client instance calls

        this once to get its client_id. No client_secret is issued (public

        clients use PKCE instead).'
      operationId: register_client_oauth_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientRegistrationRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/authorize:
    get:
      tags:
      - OAuth
      summary: Authorize
      description: 'Entry point for the browser. We validate the request params, then

        bounce the user to the frontend /oauth/consent page which handles

        Clerk login + shows the consent UI + posts back to /oauth/approve.


        The frontend preserves ALL the query params so we can reconstruct

        the auth_code request after the user clicks Allow.'
      operationId: authorize_oauth_authorize_get
      parameters:
      - name: response_type
        in: query
        required: true
        schema:
          type: string
          title: Response Type
      - name: client_id
        in: query
        required: true
        schema:
          type: string
          title: Client Id
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
          title: Redirect Uri
      - name: code_challenge
        in: query
        required: true
        schema:
          type: string
          title: Code Challenge
      - name: code_challenge_method
        in: query
        required: false
        schema:
          type: string
          default: S256
          title: Code Challenge Method
      - name: scope
        in: query
        required: false
        schema:
          type: string
          default: full
          title: Scope
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: State
      - name: resource
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Resource
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/approve:
    post:
      tags:
      - OAuth
      summary: Approve
      description: 'Frontend consent page POSTs here after the user clicks "Allow".

        Requires Clerk JWT (the user must be logged in to our platform).

        Returns the redirect URL the frontend should then navigate to

        (which lands the user back on the MCP client with ?code=...).'
      operationId: approve_oauth_approve_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/token:
    post:
      tags:
      - OAuth
      summary: Token
      description: 'Exchange an authorization code for an access token.

        Public clients: no client_secret; PKCE verifier required.'
      operationId: token_oauth_token_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_token_oauth_token_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/revoke:
    post:
      tags:
      - OAuth
      summary: Revoke
      description: 'RFC 7009 token revocation. Always returns 200 (per spec, even if

        the token doesn''t exist or was already revoked -- don''t leak which).'
      operationId: revoke_oauth_revoke_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_revoke_oauth_revoke_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ClientRegistrationRequest:
      properties:
        client_name:
          type: string
          maxLength: 120
          title: Client Name
        redirect_uris:
          items:
            type: string
          type: array
          minItems: 1
          title: Redirect Uris
        software_id:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Software Id
        software_version:
          anyOf:
          - type: string
            maxLength: 40
          - type: 'null'
          title: Software Version
        token_endpoint_auth_method:
          anyOf:
          - type: string
          - type: 'null'
          title: Token Endpoint Auth Method
        grant_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Grant Types
        response_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Response Types
        scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Scope
        client_uri:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Uri
      type: object
      required:
      - client_name
      - redirect_uris
      title: ClientRegistrationRequest
      description: 'RFC 7591 registration payload. We accept only the subset MCP clients

        actually send.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Body_revoke_oauth_revoke_post:
      properties:
        token:
          type: string
          title: Token
      type: object
      required:
      - token
      title: Body_revoke_oauth_revoke_post
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Body_token_oauth_token_post:
      properties:
        grant_type:
          type: string
          title: Grant Type
        code:
          type: string
          title: Code
        redirect_uri:
          type: string
          title: Redirect Uri
        client_id:
          type: string
          title: Client Id
        code_verifier:
          type: string
          title: Code Verifier
      type: object
      required:
      - grant_type
      - code
      - redirect_uri
      - client_id
      - code_verifier
      title: Body_token_oauth_token_post
    ApproveRequest:
      properties:
        client_id:
          type: string
          title: Client Id
        redirect_uri:
          type: string
          title: Redirect Uri
        code_challenge:
          type: string
          title: Code Challenge
        code_challenge_method:
          type: string
          title: Code Challenge Method
          default: S256
        scope:
          type: string
          title: Scope
          default: full
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
        resource:
          anyOf:
          - type: string
          - type: 'null'
          title: Resource
      type: object
      required:
      - client_id
      - redirect_uri
      - code_challenge
      title: ApproveRequest