openapi: 3.0.1
info:
  title: Ampersand public API Key Provider App API
  version: 1.0.0
servers:
- url: https://api.withampersand.com/v1
security:
- APIKeyHeader: []
- Bearer: []
tags:
- name: Provider App
paths:
  /projects/{projectIdOrName}/provider-apps:
    get:
      summary: Ampersand List Provider Apps
      operationId: listProviderApps
      tags:
      - Provider App
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: TThe Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      responses:
        200:
          description: List of provider apps
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProviderApp'
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
    post:
      summary: Ampersand Create a New Provider App
      operationId: createProviderApp
      tags:
      - Provider App
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      requestBody:
        content:
          application/json:
            schema:
              required:
              - clientId
              - clientSecret
              - provider
              type: object
              properties:
                externalRef:
                  type: string
                  description: The ID used by the provider to identify the app (optional).
                  example: external-id-123
                provider:
                  type: string
                  description: The SaaS provider that this app connects to.
                  example: salesforce
                clientId:
                  type: string
                  description: The OAuth client ID for this app.
                  example: client-id-123
                clientSecret:
                  type: string
                  description: The OAuth client secret for this app.
                  example: client-secret-123
                scopes:
                  type: array
                  description: The OAuth scopes for this app.
                  items:
                    type: string
                    example:
                    - read
                    - write
                metadata:
                  $ref: '#/components/schemas/ProviderAppMetadata'
        required: true
      responses:
        200:
          description: The newly created provider app
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderApp'
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
      x-codegen-request-body-name: providerApp
  /projects/{projectIdOrName}/provider-apps/{providerAppId}:
    delete:
      summary: Ampersand Delete a Provider App.
      operationId: deleteProviderApp
      tags:
      - Provider App
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: providerAppId
        in: path
        required: true
        description: ID of the provider app, returned by the CreateProviderApp call.
        schema:
          type: string
        example: 32356abe-d2fd-49c7-9030-abdcbc6456d4
      responses:
        204:
          description: Deleted
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
    patch:
      summary: Ampersand Update a Provider App
      operationId: updateProviderApp
      tags:
      - Provider App
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: providerAppId
        in: path
        required: true
        description: ID of the provider app, returned by the CreateProviderApp call.
        schema:
          type: string
        example: 32356abe-d2fd-49c7-9030-abdcbc6456d4
      requestBody:
        content:
          application/json:
            schema:
              required:
              - providerApp
              - updateMask
              type: object
              properties:
                updateMask:
                  type: array
                  items:
                    type: string
                  description: 'Array of field paths specifying which fields to update. Allowed values include:

                    - externalRef

                    - clientId

                    - clientSecret

                    - provider

                    - scopes

                    - metadata

                    '
                  example:
                  - externalRef
                  - clientId
                providerApp:
                  type: object
                  properties:
                    externalRef:
                      type: string
                      description: The ID used by the provider to identify the app (optional).
                      example: external-id-123
                    provider:
                      type: string
                      description: The SaaS provider that this app connects to.
                      example: salesforce
                    clientId:
                      type: string
                      description: The OAuth client ID for this app.
                      example: client-id-123
                    clientSecret:
                      type: string
                      description: The OAuth client secret for this app.
                      example: client-secret-123
                    scopes:
                      type: array
                      description: The OAuth scopes for this app.
                      items:
                        type: string
                        example:
                        - read
                        - write
                    metadata:
                      $ref: '#/components/schemas/ProviderAppMetadata'
                  description: The provider app fields to update. (Only include the fields you'd like to update.)
        required: true
      responses:
        200:
          description: The updated provider app
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderApp'
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
      x-codegen-request-body-name: providerAppUpdate
components:
  schemas:
    ProviderApp:
      title: Provider App
      required:
      - clientId
      - createTime
      - id
      - projectId
      - provider
      type: object
      properties:
        id:
          type: string
          description: The provider app ID.
          example: provider-app-123
        projectId:
          type: string
          description: The Ampersand project ID.
          example: project-456
        externalRef:
          type: string
          description: The ID used by the provider to identify the app (optional).
          example: external-id-123
        provider:
          type: string
          description: The SaaS provider that this app connects to.
          example: salesforce
        clientId:
          type: string
          description: The OAuth client ID for this app.
          example: client-id-123
        scopes:
          type: array
          description: The OAuth scopes for this app.
          items:
            type: string
            example:
            - oauth
            - offline
            - crm.read
        metadata:
          $ref: '#/components/schemas/ProviderAppMetadata'
        createTime:
          type: string
          description: The time the provider app was created.
          format: date-time
        updateTime:
          type: string
          description: The time the provider app was updated.
          format: date-time
    ProviderAppMetadata:
      title: Provider App Metadata
      type: object
      description: Provider-specific configuration that extends the standard OAuth flow.
      properties:
        authQueryParams:
          type: object
          description: Additional query parameters to include in the OAuth authorization URL (e.g., optional_scope for HubSpot).
          additionalProperties:
            type: array
            items:
              type: string
          example:
            optional_scope:
            - automation.sequences.read
        providerParams:
          type: object
          description: Provider-specific string values keyed by names (e.g., packageInstallURL for Salesforce, gcpProjectId and gcpPubSubTopicName for Gmail).
          additionalProperties:
            type: string
          example:
            packageInstallURL: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t123456789
            gcpProjectId: my-gcp-project
            gcpPubSubTopicName: my-topic
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      name: X-Api-Key
      in: header
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT