BlueOcean OAUTH Providers API

openapi: 3.2.0
info:
  title: Fast OAUTH Providers API
  version: 0.1.0
servers:
- url: /api
tags:
- name: OAuth Providers
paths:
  /auth/providers:
    get:
      tags:
      - OAuth Providers
      summary: List Providers
      description: List all supported OAuth providers.
      operationId: list_providers_auth_providers_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/providers/{provider}/authorize:
    post:
      tags:
      - OAuth Providers
      summary: Authorize Provider
      description: 'Initiate OAuth authorization flow for a provider.


        Steps:

        1. Validate provider is supported

        2. Generate OAuth state and PKCE parameters

        3. Create PENDING connection in PostgreSQL

        4. Store state in memcached for callback validation

        5. Return OAuth authorization URL


        Args:

        provider: Provider name (google, microsoft, etc.)

        request: Authorization request with user_id


        Returns:

        JSON with auth_url to redirect user to'
      operationId: authorize_provider_auth_providers__provider__authorize_post
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/{provider}/callback:
    get:
      tags:
      - OAuth Providers
      summary: Oauth Callback
      description: 'Handle OAuth callback from provider.


        Steps:

        1. Validate state parameter

        2. Handle any OAuth errors

        3. Exchange authorization code for tokens

        4. Store encrypted credentials in PostgreSQL

        5. Update connection status to CONNECTED

        6. Redirect to success page


        Args:

        provider: Provider name

        code: Authorization code from provider

        state: State parameter for validation

        error: Optional error from provider

        error_description: Optional error description


        Returns:

        HTML success page or redirect'
      operationId: oauth_callback_auth_providers__provider__callback_get
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      - name: code
        in: query
        required: true
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/{provider}/status:
    get:
      tags:
      - OAuth Providers
      summary: Check Oauth Status
      description: 'Check if user has completed OAuth for a provider.


        This is used by frontend to determine if OAuth popup is needed.


        Args:

        provider: Provider name (google, microsoft, etc.)

        user_id: User identifier


        Returns:

        { "connected": true/false, "connection_id": "...", "created_at": "..." }'
      operationId: check_oauth_status_auth_providers__provider__status_get
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/{provider}/disconnect:
    delete:
      tags:
      - OAuth Providers
      summary: Disconnect Provider
      description: 'Disconnect a provider for a user.


        Args:

        provider: Provider name

        user_id: User identifier


        Returns:

        Success message'
      operationId: disconnect_provider_auth_providers__provider__disconnect_delete
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      - name: account_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/status/all:
    get:
      tags:
      - OAuth Providers
      summary: Get All Provider Status
      description: 'Get connection status for all providers for a user.


        Args:

        user_id: User identifier


        Returns:

        List of provider connection statuses'
      operationId: get_all_provider_status_auth_providers_status_all_get
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/servers:
    get:
      tags:
      - OAuth Providers
      summary: List Provider Servers
      description: 'List all available MCP servers for a user, including both connected and unconnected.


        This endpoint returns all MCP apps that are available through OAuth providers

        (like Google Drive, Sheets, Docs) AND Pipedream apps, showing which ones are

        connected and enabled. This allows the frontend to display "Connect" buttons

        for unconnected services.


        Args:

        user_id: User identifier

        account_id: Optional account identifier for LaunchDarkly targeting


        Returns:

        Array of server objects with provider, app_id, connected status, enabled status, etc.'
      operationId: list_provider_servers_auth_providers_servers_get
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      - name: account_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/{provider}/servers/{service}:
    get:
      tags:
      - OAuth Providers
      summary: Get Provider Server
      description: 'Retrieve a specific MCP service for a user.


        This endpoint returns details for a single MCP service formatted the same way

        as items in the list_provider_servers list. Useful for checking the status

        of a specific service after enabling/disabling or for focused UI updates.


        Args:

        provider: Provider name (google, microsoft, etc.)

        service: Service/app identifier (e.g., "drive", "google_drive", "sheets", etc.)

        user_id: User identifier


        Returns:

        Single server object with provider, app_id, connected status, enabled status, etc.'
      operationId: get_provider_server_auth_providers__provider__servers__service__get
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      - name: service
        in: path
        required: true
        schema:
          type: string
          title: Service
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/{provider}/register:
    post:
      tags:
      - OAuth Providers
      summary: Register Mcp Server
      description: 'Register MCP server for a provider after OAuth is complete.


        This is the second step after OAuth authorization:

        1. OAuth authorization completes → credentials stored

        2. This endpoint → MCP server registered with agent runtime


        Args:

        provider: Provider name (google, microsoft, etc.)

        request: Registration request with user_id


        Returns:

        List of registered MCP servers in format expected by client'
      operationId: register_mcp_server_auth_providers__provider__register_post
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterMCPRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/{provider}/servers/{service}/disable:
    put:
      tags:
      - OAuth Providers
      summary: Disable Mcp Service
      description: 'Disable a specific MCP service for a user.


        This removes the service''s tools from the agent context without

        deleting OAuth tokens or unregistering the connection.


        Args:

        provider: Provider name (google, microsoft, etc.)

        service: App ID or service name (google_sheets, sheets, etc.)

        user_id: User identifier


        Returns:

        Full list of provider servers with updated enabled/disabled status'
      operationId: disable_mcp_service_auth_providers__provider__servers__service__disable_put
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      - name: service
        in: path
        required: true
        schema:
          type: string
          title: Service
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      - name: account_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/{provider}/servers/{service}/enable:
    put:
      tags:
      - OAuth Providers
      summary: Enable Mcp Service
      description: 'Re-enable a previously disabled MCP service.


        This re-registers the MCP server and makes its tools available to the agent.


        Args:

        provider: Provider name (google, microsoft, etc.)

        service: App ID or service name (google_sheets, sheets, etc.)

        user_id: User identifier


        Returns:

        Full list of provider servers with updated enabled/disabled status'
      operationId: enable_mcp_service_auth_providers__provider__servers__service__enable_put
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      - name: service
        in: path
        required: true
        schema:
          type: string
          title: Service
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      - name: account_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/mcp/servers:
    get:
      tags:
      - OAuth Providers
      summary: List Mcp Servers
      description: 'List all MCP servers registered for a user.


        This endpoint returns all MCP servers that have been registered via OAuth,

        including their connection status, tool counts, and metadata.


        Args:

        user_id: User identifier


        Returns:

        List of MCP server details with OAuth provider information'
      operationId: list_mcp_servers_auth_providers_mcp_servers_get
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/mcp/servers/{server_name}:
    get:
      tags:
      - OAuth Providers
      summary: Get Mcp Server
      description: 'Get details for a specific MCP server.


        Args:

        server_name: Name of the MCP server

        user_id: User identifier (for authorization)


        Returns:

        Detailed server information including tools'
      operationId: get_mcp_server_auth_providers_mcp_servers__server_name__get
      parameters:
      - name: server_name
        in: path
        required: true
        schema:
          type: string
          title: Server Name
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - OAuth Providers
      summary: Remove Mcp Server
      description: 'Remove/unregister an MCP server.


        This only removes the MCP server registration from memory.

        The OAuth connection remains active in the database.

        To fully disconnect, use DELETE /auth/providers/{provider}/disconnect


        Args:

        server_name: Name of the MCP server to remove

        user_id: User identifier (for authorization)


        Returns:

        Formatted list of remaining active servers (same format as GET /mcp/servers)'
      operationId: remove_mcp_server_auth_providers_mcp_servers__server_name__delete
      parameters:
      - name: server_name
        in: path
        required: true
        schema:
          type: string
          title: Server Name
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/mcp/servers/{server_name}/refresh:
    post:
      tags:
      - OAuth Providers
      summary: Refresh Mcp Server
      description: 'Refresh an MCP server''s tools and update its token if needed.


        This is useful when:

        - Tools have been added/removed from the MCP server

        - OAuth token has been refreshed

        - Server needs to be re-initialized


        Args:

        server_name: Name of the MCP server to refresh

        user_id: User identifier (for authorization)


        Returns:

        Updated server information'
      operationId: refresh_mcp_server_auth_providers_mcp_servers__server_name__refresh_post
      parameters:
      - name: server_name
        in: path
        required: true
        schema:
          type: string
          title: Server Name
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/providers/mcp/stats:
    get:
      tags:
      - OAuth Providers
      summary: Get Mcp Stats
      description: 'Get MCP usage statistics for a user.


        Args:

        user_id: User identifier


        Returns:

        Statistics about MCP servers and tools'
      operationId: get_mcp_stats_auth_providers_mcp_stats_get
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RegisterMCPRequest:
      properties:
        user_id:
          type: string
          title: User Id
        provider:
          type: string
          title: Provider
        service:
          anyOf:
          - type: string
          - type: 'null'
          title: Service
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
      type: object
      required:
      - user_id
      - provider
      title: RegisterMCPRequest
      description: Request to register MCP server for a provider.
    AuthorizeRequest:
      properties:
        user_id:
          type: string
          title: User Id
        redirect_uri:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Uri
        state_metadata:
          anyOf:
          - type: object
          - type: 'null'
          title: State Metadata
        service:
          anyOf:
          - type: string
          - type: 'null'
          title: Service
      type: object
      required:
      - user_id
      title: AuthorizeRequest
      description: Request to initiate OAuth authorization.
    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