openapi: 3.1.0
info:
  title: PropelAuth MCP Authentication API
  description: |
    OAuth 2.1 authorization server endpoints PropelAuth exposes for Model Context Protocol
    (MCP) clients and AI agents. Includes dynamic client registration (RFC 7591), token
    introspection, and the OAuth 2.1 authorization server metadata endpoint. Use this to
    secure MCP servers with PropelAuth identities and organization-scoped permissions.
  version: "1.0.0"
  contact:
    name: PropelAuth Support
    url: https://www.propelauth.com
    email: support@propelauth.com
  license:
    name: PropelAuth Terms
    url: https://www.propelauth.com/legal/terms-of-service
servers:
  - url: https://auth.example.com
    description: Your PropelAuth Auth URL
tags:
  - name: MCP OAuth 2.1
    description: OAuth 2.1 flows for MCP clients
  - name: Dynamic Client Registration
    description: RFC 7591 dynamic client registration
  - name: Metadata
    description: Authorization server metadata discovery
paths:
  /oauth/2.1/authorize:
    get:
      summary: MCP Authorize
      description: Begin an OAuth 2.1 authorization code flow with PKCE for an MCP client.
      operationId: mcpAuthorize
      tags: [MCP OAuth 2.1]
      parameters:
        - name: response_type
          in: query
          required: true
          schema: { type: string, enum: [code] }
        - name: client_id
          in: query
          required: true
          schema: { type: string }
        - name: redirect_uri
          in: query
          required: true
          schema: { type: string, format: uri }
        - name: scope
          in: query
          schema: { type: string, example: "read:user_data tools:execute" }
        - name: state
          in: query
          schema: { type: string }
        - name: code_challenge
          in: query
          required: true
          schema: { type: string }
        - name: code_challenge_method
          in: query
          required: true
          schema: { type: string, enum: [S256] }
      responses:
        '302':
          description: Redirect to login or to redirect_uri with authorization code
  /oauth/2.1/token:
    post:
      summary: MCP Token
      description: Exchange an authorization code for tokens, or refresh an existing token.
      operationId: mcpToken
      tags: [MCP OAuth 2.1]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [grant_type, client_id]
              properties:
                grant_type:
                  type: string
                  enum: [authorization_code, refresh_token]
                code: { type: string }
                redirect_uri: { type: string, format: uri }
                refresh_token: { type: string }
                client_id: { type: string }
                client_secret: { type: string }
                code_verifier: { type: string }
      responses:
        '200':
          description: Token issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token: { type: string }
                  refresh_token: { type: string }
                  token_type: { type: string }
                  expires_in: { type: integer }
                  scope: { type: string }
  /oauth/2.1/introspect:
    post:
      summary: MCP Introspect
      description: Validate an access token and return associated user, organization, and scope information.
      operationId: mcpIntrospect
      tags: [MCP OAuth 2.1]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [token]
              properties:
                token: { type: string }
                token_type_hint: { type: string, enum: [access_token, refresh_token] }
      responses:
        '200':
          description: Introspection result
          content:
            application/json:
              schema:
                type: object
                properties:
                  active: { type: boolean }
                  scope: { type: string }
                  client_id: { type: string }
                  username: { type: string }
                  sub: { type: string }
                  exp: { type: integer }
                  iat: { type: integer }
                  org_id: { type: string, format: uuid }
                  org_role: { type: string }
  /oauth/2.1/register:
    post:
      summary: Dynamic Client Registration
      description: |
        Register a new MCP client dynamically. Requires that dynamic client registration is
        enabled for your PropelAuth instance.
      operationId: mcpRegister
      tags: [Dynamic Client Registration]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [redirect_uris]
              properties:
                redirect_uris:
                  type: array
                  items: { type: string, format: uri }
                client_name: { type: string }
                client_uri: { type: string, format: uri }
                token_endpoint_auth_method:
                  type: string
                  enum: [none, client_secret_basic, client_secret_post]
                grant_types:
                  type: array
                  items:
                    type: string
                    enum: [authorization_code, refresh_token]
                response_types:
                  type: array
                  items: { type: string, enum: [code] }
                scope: { type: string }
      responses:
        '201':
          description: Client registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_id: { type: string }
                  client_secret: { type: string }
                  client_id_issued_at: { type: integer }
                  client_secret_expires_at: { type: integer }
                  redirect_uris:
                    type: array
                    items: { type: string }
  /.well-known/oauth-authorization-server/oauth/2.1:
    get:
      summary: OAuth 2.1 Authorization Server Metadata
      description: |
        OAuth 2.1 authorization server metadata document, including supported scopes, grant
        types, response types, and PKCE methods.
      operationId: mcpAuthServerMetadata
      tags: [Metadata]
      responses:
        '200':
          description: Metadata document
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuer: { type: string, format: uri }
                  authorization_endpoint: { type: string, format: uri }
                  token_endpoint: { type: string, format: uri }
                  introspection_endpoint: { type: string, format: uri }
                  registration_endpoint: { type: string, format: uri }
                  scopes_supported:
                    type: array
                    items: { type: string }
                  response_types_supported:
                    type: array
                    items: { type: string }
                  grant_types_supported:
                    type: array
                    items: { type: string }
                  code_challenge_methods_supported:
                    type: array
                    items: { type: string }