@celigo/api-specs 0.2.1

package/dist/mcp-oauth-provider.yml

@@ -0,0 +1,590 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: MCP OAuth Providers
+  description: API for managing Celigo MCP OAuth providers — reusable OAuth 2.0 token-validation configurations referenced by MCP servers.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: MCP OAuth Providers
+    description: |-
+      MCP OAuth providers are reusable OAuth 2.0 configurations referenced by
+      MCP servers. Each provider holds an issuer URL, audience, optional scopes,
+      and optional introspection settings. Multiple MCP servers can reference
+      the same provider via `_mcpOAuthProviderId`, avoiding duplicated OAuth
+      configuration.
+
+      Providers support two token validation modes: JWT validation against the
+      issuer's JWKS endpoint (default), or RFC 7662 introspection for opaque
+      tokens when `useIntrospection` is enabled with `clientId`/`clientSecret`.
+
+      ## MCP OAuth provider schema
+
+      {% openapi-schemas spec="mcp-oauth-provider" schemas="MCPOAuthProvider" grouped="true" %}
+paths:
+  /v1/mcpoauthproviders:
+    get:
+      x-internal: false
+      summary: List MCP OAuth providers
+      description: Returns all MCP OAuth providers in the account.
+      operationId: listMcpOauthProviders
+      tags:
+        - MCP OAuth Providers
+      parameters:
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+      responses:
+        '200':
+          description: Provider list.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/MCPOAuthProvider'
+              examples:
+                default:
+                  value:
+                    - _id: 69fcae29459e338098b54257
+                      _userId: 624cb0346309dc3a543733a2
+                      name: auth.example.com
+                      description: Production Auth0 tenant
+                      issuerURL: https://auth.example.com
+                      audience: https://mcp.example.com
+                      scopes:
+                        - mcp:read
+                        - mcp:write
+                      useIntrospection: true
+                      clientId: my-client-id
+                      clientSecret: '******'
+                      createdAt: '2026-05-07T15:22:16.998Z'
+                      lastModified: '2026-05-07T15:22:16.998Z'
+        '204':
+          description: No providers exist in the account.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    post:
+      x-internal: false
+      summary: Create an MCP OAuth provider
+      description: |-
+        Creates a reusable OAuth provider that MCP servers can reference via
+        `_mcpOAuthProviderId`. `name`, `issuerURL`, and `audience` are
+        required. Set `useIntrospection: true` with `clientId`/`clientSecret`
+        to support opaque (non-JWT) tokens.
+      operationId: createMcpOauthProvider
+      tags:
+        - MCP OAuth Providers
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              jwt_only:
+                summary: JWT-only validation
+                value:
+                  name: auth.example.com
+                  issuerURL: https://auth.example.com
+                  audience: https://mcp.example.com
+                  scopes:
+                    - mcp:read
+                    - mcp:write
+              with_introspection:
+                summary: With opaque token introspection
+                value:
+                  name: auth.example.com
+                  issuerURL: https://auth.example.com
+                  audience: https://mcp.example.com
+                  scopes:
+                    - mcp:read
+                  useIntrospection: true
+                  clientId: my-client-id
+                  clientSecret: my-client-secret
+      responses:
+        '201':
+          description: Created provider.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPOAuthProvider'
+              examples:
+                created:
+                  summary: Created provider with introspection (secret masked, description defaults to empty)
+                  value:
+                    _id: 69fcae29459e338098b54257
+                    _userId: 624cb0346309dc3a543733a2
+                    name: auth.example.com
+                    description: ''
+                    issuerURL: https://auth.example.com
+                    audience: https://api.example.com
+                    useIntrospection: true
+                    clientId: cid123
+                    clientSecret: '******'
+                    createdAt: '2026-05-07T15:22:16.998Z'
+                    lastModified: '2026-05-07T15:22:16.998Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/mcpoauthproviders/{_id}:
+    get:
+      x-internal: false
+      summary: Get an MCP OAuth provider
+      description: Returns the full configuration of an MCP OAuth provider.
+      operationId: getMcpOauthProviderById
+      tags:
+        - MCP OAuth Providers
+      parameters:
+        - name: _id
+          in: path
+          description: Provider ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpoauthproviders
+            examples:
+              - 69fcae29459e338098b54257
+      responses:
+        '200':
+          description: Provider configuration.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPOAuthProvider'
+              examples:
+                default:
+                  summary: Provider with introspection and scoped access
+                  value:
+                    _id: 69fcae29459e338098b54257
+                    _userId: 624cb0346309dc3a543733a2
+                    name: auth.example.com
+                    description: Production Auth0 tenant
+                    issuerURL: https://auth.example.com
+                    audience: https://mcp.example.com
+                    scopes:
+                      - mcp:read
+                      - mcp:write
+                    useIntrospection: true
+                    clientId: my-client-id
+                    clientSecret: '******'
+                    createdAt: '2026-05-07T15:22:16.998Z'
+                    lastModified: '2026-05-07T15:22:16.998Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update an MCP OAuth provider
+      description: |-
+        Full replacement of an MCP OAuth provider's configuration --
+        include all fields, not just the ones you want to change. Send
+        `clientSecret: "******"` to preserve the existing secret. Changes
+        propagate to all MCP servers referencing this provider.
+      operationId: updateMcpOauthProvider
+      tags:
+        - MCP OAuth Providers
+      parameters:
+        - name: _id
+          in: path
+          description: Provider ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpoauthproviders
+            examples:
+              - 69fcae29459e338098b54257
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              add_scope:
+                summary: Add the mcp:write scope (send masked secret to preserve it)
+                value:
+                  name: auth.example.com
+                  description: Production Auth0 tenant
+                  issuerURL: https://auth.example.com
+                  audience: https://mcp.example.com
+                  scopes:
+                    - mcp:read
+                    - mcp:write
+                  useIntrospection: true
+                  clientId: my-client-id
+                  clientSecret: '******'
+      responses:
+        '200':
+          description: Updated provider.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPOAuthProvider'
+              examples:
+                updated:
+                  summary: Provider with mcp:write scope added
+                  value:
+                    _id: 69fcae29459e338098b54257
+                    _userId: 624cb0346309dc3a543733a2
+                    name: auth.example.com
+                    description: Production Auth0 tenant
+                    issuerURL: https://auth.example.com
+                    audience: https://mcp.example.com
+                    scopes:
+                      - mcp:read
+                      - mcp:write
+                    useIntrospection: true
+                    clientId: my-client-id
+                    clientSecret: '******'
+                    createdAt: '2026-05-07T15:22:16.998Z'
+                    lastModified: '2026-05-08T10:02:44.310Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      summary: Delete an MCP OAuth provider
+      description: |-
+        Deletes an MCP OAuth provider. MCP servers referencing this
+        provider via `_mcpOAuthProviderId` will lose their OAuth
+        configuration.
+      operationId: deleteMcpOauthProvider
+      tags:
+        - MCP OAuth Providers
+      parameters:
+        - name: _id
+          in: path
+          description: Provider ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpoauthproviders
+            examples:
+              - 69fcae29459e338098b54257
+      responses:
+        '204':
+          description: Deleted.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    Include:
+      name: include
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to project into each returned record.
+        Triggers summary projection: the response contains a minimal identity
+        set (`_id`, `name`, plus resource-specific fields) with the requested
+        fields added on top. Supports dot notation for nested fields.
+        Mutually exclusive with `exclude`.
+      schema:
+        type: string
+      example: _integrationId,disabled,lastModified
+    Exclude:
+      name: exclude
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to strip from the default response.
+        Unlike `include`, does not trigger summary projection — returns the
+        full record with the named fields removed. Protected identity fields
+        (e.g. `name`) cannot be stripped. Mutually exclusive with `include`.
+      schema:
+        type: string
+      example: createdAt,lastModified
+  schemas:
+    MCPOAuthProviderBase:
+      type: object
+      description: Writable MCP OAuth provider fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 150
+          description: Display name for the OAuth provider.
+          examples:
+            - auth.example.com
+        description:
+          type: string
+          description: Description of the provider's purpose.
+          examples:
+            - Production Auth0 tenant for MCP servers
+        issuerURL:
+          type: string
+          format: uri
+          description: |-
+            OAuth 2.0 issuer URL. Must include `http://` or `https://` scheme.
+            Bare hostnames are rejected.
+          examples:
+            - https://auth.example.com
+        audience:
+          type: string
+          description: Expected `aud` claim on incoming access tokens.
+          examples:
+            - https://mcp.example.com
+        scopes:
+          type: array
+          description: Required OAuth scopes. Incoming tokens must carry every listed scope.
+          items:
+            type: string
+            enum:
+              - mcp:read
+              - mcp:write
+            x-enumDescriptions:
+              mcp:read: Grants read-only access to MCP server resources.
+              mcp:write: Grants write access to MCP server resources.
+          examples:
+            - - mcp:read
+              - mcp:write
+        useIntrospection:
+          type: boolean
+          default: false
+          description: |-
+            When `true`, opaque access tokens are validated via the issuer's
+            RFC 7662 introspection endpoint using `clientId`/`clientSecret`.
+            When `false`, only JWT tokens validated against JWKS are accepted.
+        clientId:
+          type:
+            - string
+            - 'null'
+          description: |-
+            OAuth client ID for token introspection. Required when
+            `useIntrospection` is `true`.
+          examples:
+            - my-client-id
+        clientSecret:
+          type:
+            - string
+            - 'null'
+          description: |-
+            OAuth client secret for introspection. Masked as `"******"` in
+            responses; sending the masked value on PUT leaves it unchanged.
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    MCPOAuthProvider:
+      type: object
+      required:
+        - _id
+        - name
+        - issuerURL
+        - audience
+        - createdAt
+        - lastModified
+      description: MCP OAuth provider object as returned by the API.
+      allOf:
+        - $ref: '#/components/schemas/MCPOAuthProviderBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _userId:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: users
+              description: Owning user ID.
+              examples:
+                - 624cb0346309dc3a543733a2
+    Request:
+      type: object
+      description: |-
+        Request body for creating or updating an MCP OAuth provider. On PUT,
+        this is a full replacement; include all fields you want to keep because
+        omitted optional fields are cleared.
+      required:
+        - name
+        - issuerURL
+        - audience
+      allOf:
+        - $ref: '#/components/schemas/MCPOAuthProviderBase'
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+x-enable-proxy: true
+x-internal: false