openapi: 3.2.0
info:
  title: Pipeshub OpenID Connect API
  version: 1.0.0
  contact:
    name: API Support
    email: support@pipeshub.com
  description: 'Operations tagged OpenID Connect across 2 of this provider''s published API definitions: pipeshub-openapi.yaml, pipeshub-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{instance_url}/api/v1'
  description: Base API URL
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL (without /api/v1)
- url: '{instance_url}'
  description: Root URL (used for MCP endpoints mounted at /mcp)
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL
security:
- bearerAuth: []
- oauth2: []
tags:
- name: OpenID Connect
  description: OpenID Connect 1.0 endpoints for identity federation and discovery.
paths:
  /oauth2/userinfo:
    get:
      tags:
      - OpenID Connect
      summary: Get authenticated user information
      description: 'OpenID Connect UserInfo Endpoint.


        Returns claims about the authenticated user. Requires a valid access token

        with the `openid` scope.


        **Available Claims:**

        - `user_id` - User identifier

        - `name`, `given_name`, `family_name` - Name claims (with `profile` scope)

        - `email`, `email_verified` - Email claims (with `email` scope)


        **Authentication:**

        Pass the access token as a Bearer token: `Authorization: Bearer {access_token}`'
      operationId: oauthUserInfo
      x-pipeshub-sdk: true
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthUserInfoResponse'
              example:
                user_id: user-id-123
                name: John Doe
                given_name: John
                family_name: Doe
                email: john.doe@example.com
                email_verified: true
        '401':
          description: Invalid or missing access token
        '403':
          description: Token does not have openid scope
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /.well-known/openid-configuration:
    get:
      tags:
      - OpenID Connect
      summary: OpenID Connect Discovery
      description: 'OpenID Connect Discovery Endpoint (RFC 8414).


        Returns metadata about the OAuth/OIDC authorization server including

        endpoint URLs, supported features, and capabilities.


        Use Cases:


        - Automatic client configuration


        - Discovering supported features


        - Getting endpoint URLs without hardcoding


        Note: This endpoint does not require authentication.'
      operationId: openidConfiguration
      security: []
      servers:
      - url: /
        description: Root URL (not /api/v1)
      responses:
        '200':
          description: Authorization server metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIDConfiguration'
              example:
                issuer: https://api.pipeshub.com
                authorization_endpoint: https://api.pipeshub.com/oauth2/authorize
                token_endpoint: https://api.pipeshub.com/oauth2/token
                userinfo_endpoint: https://api.pipeshub.com/oauth2/userinfo
                revocation_endpoint: https://api.pipeshub.com/oauth2/revoke
                introspection_endpoint: https://api.pipeshub.com/oauth2/introspect
                jwks_uri: https://api.pipeshub.com/.well-known/jwks.json
                scopes_supported:
                - openid
                - profile
                - email
                - read:records
                - write:records
                response_types_supported:
                - code
                grant_types_supported:
                - authorization_code
                - client_credentials
                - refresh_token
                token_endpoint_auth_methods_supported:
                - client_secret_basic
                - client_secret_post
                code_challenge_methods_supported:
                - S256
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - OpenID Connect
      summary: OAuth 2.0 Authorization Server Metadata
      description: 'OAuth 2.0 Authorization Server Metadata Endpoint (RFC 8414).


        Returns the same metadata as the OpenID Connect Discovery endpoint

        but at the RFC 8414 standard path. MCP clients like Claude Code use

        this endpoint for discovery instead of openid-configuration.


        Note: This endpoint does not require authentication.'
      operationId: oauthAuthorizationServerMetadata
      security: []
      servers:
      - url: /
        description: Root URL (not /api/v1)
      responses:
        '200':
          description: Authorization server metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIDConfiguration'
              example:
                issuer: https://api.pipeshub.com
                authorization_endpoint: https://api.pipeshub.com/oauth2/authorize
                token_endpoint: https://api.pipeshub.com/oauth2/token
                userinfo_endpoint: https://api.pipeshub.com/oauth2/userinfo
                revocation_endpoint: https://api.pipeshub.com/oauth2/revoke
                introspection_endpoint: https://api.pipeshub.com/oauth2/introspect
                jwks_uri: https://api.pipeshub.com/.well-known/jwks.json
                scopes_supported:
                - openid
                - profile
                - email
                - read:records
                - write:records
                response_types_supported:
                - code
                grant_types_supported:
                - authorization_code
                - client_credentials
                - refresh_token
                token_endpoint_auth_methods_supported:
                - client_secret_basic
                - client_secret_post
                code_challenge_methods_supported:
                - S256
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /.well-known/jwks.json:
    get:
      tags:
      - OpenID Connect
      summary: JSON Web Key Set
      description: 'JSON Web Key Set Endpoint (RFC 7517).


        Returns the public keys used to verify JWT signatures for ID tokens

        and access tokens.


        Use Cases:


        - Verifying ID token signatures


        - Verifying access token signatures (if JWT-based)


        Note:


        - For HS256 (symmetric) signing, this returns empty keys


        - For RS256 (asymmetric) signing, returns public RSA keys


        - Keys should be cached with appropriate TTL'
      operationId: jwks
      security: []
      servers:
      - url: /
        description: Root URL (not /api/v1)
      responses:
        '200':
          description: JSON Web Key Set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWKS'
              example:
                keys:
                - kty: RSA
                  use: sig
                  alg: RS256
                  kid: key-1
                  n: 0vx7agoebG...
                  e: AQAB
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /.well-known/oauth-protected-resource/mcp:
    get:
      tags:
      - OpenID Connect
      summary: OAuth Protected Resource Metadata
      description: 'OAuth Protected Resource Metadata Endpoint (RFC 9728).


        Returns metadata about the protected resource including the resource

        identifier, authorization servers, supported scopes, and bearer token methods.


        Use Cases:


        - Discovering which authorization server to use for this resource


        - Determining supported scopes and bearer token methods


        - MCP client auto-configuration


        Note: This endpoint does not require authentication.'
      operationId: oauthProtectedResource
      security: []
      servers:
      - url: /
        description: Root URL (not /api/v1)
      responses:
        '200':
          description: Protected resource metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProtectedResourceMetadata'
              example:
                resource: https://api.pipeshub.com/mcp
                authorization_servers:
                - https://api.pipeshub.com
                scopes_supported:
                - read:records
                - write:records
                - admin:connectors
                bearer_methods_supported:
                - header
                resource_documentation: https://api.pipeshub.com/api/v1/docs
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
components:
  schemas:
    OpenIDConfiguration:
      type: object
      description: 'OpenID Connect Discovery Response (RFC 8414).

        Contains authorization server metadata.

        '
      properties:
        issuer:
          type: string
          format: uri
          description: Authorization server issuer URL
        authorization_endpoint:
          type: string
          format: uri
          description: OAuth authorization endpoint
        token_endpoint:
          type: string
          format: uri
          description: OAuth token endpoint
        userinfo_endpoint:
          type: string
          format: uri
          description: OpenID Connect UserInfo endpoint
        revocation_endpoint:
          type: string
          format: uri
          description: Token revocation endpoint
        introspection_endpoint:
          type: string
          format: uri
          description: Token introspection endpoint
        jwks_uri:
          type: string
          format: uri
          description: JSON Web Key Set endpoint
        scopes_supported:
          type: array
          items:
            type: string
          description: Supported OAuth scopes
          example:
          - openid
          - profile
          - email
          - read:records
          - write:records
        response_types_supported:
          type: array
          items:
            type: string
          description: Supported OAuth response types
          example:
          - code
        grant_types_supported:
          type: array
          items:
            type: string
          description: Supported grant types
          example:
          - authorization_code
          - client_credentials
          - refresh_token
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
          description: Supported client authentication methods
          example:
          - client_secret_basic
          - client_secret_post
        subject_types_supported:
          type: array
          items:
            type: string
          description: Supported subject identifier types
          example:
          - public
        id_token_signing_alg_values_supported:
          type: array
          items:
            type: string
          description: Supported ID token signing algorithms
          example:
          - HS256
          - RS256
        claims_supported:
          type: array
          items:
            type: string
          description: Supported claims in ID tokens/UserInfo
          example:
          - user_id
          - iss
          - aud
          - exp
          - iat
          - email
          - name
        code_challenge_methods_supported:
          type: array
          items:
            type: string
          description: Supported PKCE code challenge methods (only `S256`)
          example:
          - S256
    OAuthProtectedResourceMetadata:
      type: object
      description: 'OAuth Protected Resource Metadata (RFC 9728).

        Describes the protected resource, its authorization servers, supported scopes, and bearer token methods.

        '
      required:
      - resource
      - authorization_servers
      properties:
        resource:
          type: string
          format: uri
          description: Protected resource identifier
        authorization_servers:
          type: array
          items:
            type: string
            format: uri
          description: Authorization servers that can issue tokens for this resource
        scopes_supported:
          type: array
          items:
            type: string
          description: OAuth scopes supported by this resource
          example:
          - read:records
          - write:records
          - admin:connectors
        bearer_methods_supported:
          type: array
          items:
            type: string
          description: Methods supported for sending bearer tokens
          example:
          - header
        resource_documentation:
          type: string
          format: uri
          description: URL to human-readable documentation for the resource
    JWKS:
      type: object
      description: 'JSON Web Key Set (RFC 7517).

        Contains public keys for verifying token signatures.

        '
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/JWK'
          description: Array of JSON Web Keys
    JWK:
      type: object
      description: 'JSON Web Key (RFC 7517).

        Public key for verifying JWT signatures.

        '
      properties:
        kty:
          type: string
          description: Key type
          example: RSA
        use:
          type: string
          description: Key use (sig = signature)
          example: sig
        alg:
          type: string
          description: Algorithm
          example: RS256
        kid:
          type: string
          description: Key ID
        n:
          type: string
          description: RSA modulus (base64url encoded)
        e:
          type: string
          description: RSA exponent (base64url encoded)
          example: AQAB
    OAuthUserInfoResponse:
      type: object
      description: 'OpenID Connect UserInfo Response.

        Contains claims about the authenticated user.

        '
      properties:
        user_id:
          type: string
          description: User ID
        name:
          type: string
          description: Full name
        given_name:
          type: string
          description: First name
        family_name:
          type: string
          description: Last name
        email:
          type: string
          format: email
          description: Email address
        email_verified:
          type: boolean
          description: Whether email has been verified
        picture:
          type: string
          format: uri
          description: Profile picture URL
        updated_at:
          type: integer
          description: Last profile update timestamp (Unix epoch)
      required:
      - user_id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT Bearer token for authenticated requests.


        A personal access token (see the **Personal Access Tokens** tag) is a

        `phpat_`-prefixed variant of this same JWT — e.g. `phpat_eyJhbGci...`.

        The prefix is display-only, added for secret-scanner detectability; the

        gateway strips it before verifying the token, so send it exactly as

        issued, prefix included.

        '
    scopedToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Scoped JWT token for service-to-service authentication.

        Format: "Bearer {scoped_token}"

        Required scopes vary by endpoint.

        '
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 authentication with fine-grained scopes.

        Supports authorization_code (with PKCE) and client_credentials flows.

        OAuth tokens are Bearer JWTs — use the same Authorization header as regular tokens.

        For **client_credentials**, machine JWTs may use `userId === client_id`; the Node gateway resolves the OAuth app creator — see **OAuth Provider** tag.

        '
      flows:
        authorizationCode:
          authorizationUrl: /api/v1/oauth2/authorize
          tokenUrl: /api/v1/oauth2/token
          refreshUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:read: Read semantic search results and history
            semantic:write: Execute semantic search
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
            crawl:delete: Delete crawling jobs
        clientCredentials:
          tokenUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:write: Execute semantic search
            semantic:read: Read semantic search results and history
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
x-refined-from:
- pipeshub-openapi.yaml
- pipeshub-openapi.yml