openapi: 3.0.1
info:
  title: Ampersand public API Key Connection API
  version: 1.0.0
servers:
- url: https://api.withampersand.com/v1
security:
- APIKeyHeader: []
- Bearer: []
tags:
- name: Connection
paths:
  /projects/{projectIdOrName}/connections:
    get:
      summary: Ampersand List Connections
      operationId: listConnections
      tags:
      - Connection
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: provider
        in: query
        description: The provider name (e.g. "salesforce", "hubspot")
        schema:
          type: string
      - name: groupRef
        in: query
        description: The ID of the user group that has access to this installation.
        example: group-123
        schema:
          type: string
      - name: consumerRef
        in: query
        description: The consumer reference.
        schema:
          type: string
      responses:
        200:
          description: List of project connections.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Connection'
        404:
          description: Not Found
          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
  /projects/{projectIdOrName}/connections:generate:
    post:
      summary: Ampersand Generate a New Connection
      description: All auth schemes are supported, but for OAuth2 Authorization Code, it is recommended that you use the [/oauth-connect endpoint](https://docs.withampersand.com/reference/oauth/get-url-for-oauth-flow) instead, unless you already have the refresh token and are importing it into Ampersand.
      operationId: generateConnection
      tags:
      - Connection
      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:
              $ref: '#/components/schemas/GenerateConnectionRequest'
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        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: generateConnectionParams
  /projects/{projectIdOrName}/connections/{connectionId}:
    get:
      summary: Ampersand Get a Connection
      operationId: getConnection
      tags:
      - Connection
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
      - name: includeCreds
        in: query
        schema:
          type: boolean
        description: Whether to include credentials for `oauth2AuthorizationCode` in the response. If true, `accessToken` and `scopes` are included. To include `refreshToken` as well, set `includeRefreshToken` to true. Default is false.
      - name: includeRefreshToken
        in: query
        schema:
          type: boolean
        description: Whether to include `refreshToken` for `oauth2AuthorizationCode` credentials in the response (along with `accessToken` and `scopes`). If true, the `includeCreds` query parameter will be ignored. Default is false.
      - name: refresh
        in: query
        schema:
          type: string
          enum:
          - force
          - ifExpired
        description: Whether to refresh the access token. If value is `ifExpired`, the access token will be refreshed only if it has expired. If value is `force`, the access token will be refreshed regardless of its expiration.
      responses:
        200:
          description: Connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        404:
          description: Not Found
          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 Connection.
      description: Rotate credentials or update metadata (such as the provider workspace reference) for an existing connection.
      operationId: updateConnection
      tags:
      - Connection
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: The Ampersand project ID or project name.
        example: my-project
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the connection to update. You can find this via the [list connections endpoint](https://docs.withampersand.com/reference/connection/list-connections).
        example: connection-123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectionRequest'
            examples:
              rotateApiKey:
                summary: Rotate an API key
                value:
                  updateMask:
                  - apiKey
                  connection:
                    apiKey: new-api-key-value
              updateBasicAuth:
                summary: Update basic auth credentials
                value:
                  updateMask:
                  - basicAuth
                  connection:
                    basicAuth:
                      username: new-username
                      password: new-password
              updateWorkspaceRef:
                summary: Update provider workspace reference
                value:
                  updateMask:
                  - providerWorkspaceRef
                  connection:
                    providerWorkspaceRef: new-workspace-id
      responses:
        '200':
          description: Connection updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
              example:
                id: c3a1f9d2-7b4e-4f8a-9e6d-2c5b8a3f1e7d
                projectId: a1b2c3d4-e5f6-4789-a012-3456789abcde
                provider: salesforce
                group:
                  groupRef: 8f2e4a6b-1c3d-4e5f-9a7b-0d8e6f2c4a1b
                  groupName: my-group
                consumer:
                  consumerRef: d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a
                  consumerName: my-consumer
                providerWorkspaceRef: my-org.my.salesforce.com
                authScheme: apiKey
                status: working
                createTime: '2023-07-13T21:34:44.816354Z'
                updateTime: '2024-01-15T10:22:33.000000Z'
        400:
          description: Invalid update mask or request body. The response includes the list of allowed mask values.
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
              example:
                type: about:blank
                title: Bad Request
                status: 400
                detail: Invalid update mask
                subsystem: api
                time: '2024-04-22T18:55:28.456076Z'
                requestId: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715
                remedy: 'Allowed masks: ''providerWorkspaceRef, providerMetadata, apiKey, basicAuth, oauth2ClientCredentials, oauth2PasswordCredentials'''
                retryable: false
        default:
          description: Error (e.g. connection not found, auth scheme mismatch, or server error).
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
    delete:
      summary: Ampersand Delete a Connection
      operationId: deleteConnection
      tags:
      - Connection
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
      responses:
        204:
          description: Deleted
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
components:
  schemas:
    Consumer:
      title: Consumer
      required:
      - consumerName
      - consumerRef
      - createTime
      - projectId
      type: object
      properties:
        consumerRef:
          type: string
          description: The consumer reference.
          example: consumer-123
        consumerName:
          type: string
          description: The name of the consumer.
          example: Super Customer
        projectId:
          type: string
          description: The Ampersand project ID.
          example: project-456
        createTime:
          type: string
          description: The time the consumer was created.
          format: date-time
          example: 2023-07-13 21:34:44.816354+00:00
        updateTime:
          type: string
          description: The time the consumer was last updated.
          format: date-time
          example: 2023-07-13 21:34:44.816354+00:00
    GenerateConnectionRequest:
      title: Generate Connection Request
      allOf:
      - $ref: '#/components/schemas/ConnectionRequest'
      - type: object
        required:
        - groupRef
        - consumerRef
        - provider
    ProviderMetadataInfo:
      title: Provider Metadata Info
      type: object
      required:
      - value
      - source
      properties:
        value:
          type: string
          description: The value of the metadata field
          example: '1234567890'
        source:
          type: string
          description: The source of the metadata field
          enum:
          - input
          - token
          - provider
          example: input
        displayName:
          type: string
          description: The human-readable name for the field
          example: Account ID
    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
    Group:
      title: Group
      required:
      - createTime
      - groupName
      - groupRef
      - projectId
      type: object
      properties:
        groupRef:
          type: string
          description: The ID of the user group that has access to this installation.
          example: group-123
        groupName:
          type: string
          description: The name of the user group that has access to this installation.
          example: Super Customer
        projectId:
          type: string
          description: The Ampersand project ID.
          example: project-456
        createTime:
          type: string
          description: The time the group was created.
          format: date-time
          example: 2023-07-13 21:34:44.816354+00:00
        updateTime:
          type: string
          description: The time the group was last updated.
          format: date-time
          example: 2023-07-13 21:34:44.816354+00:00
    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
    Oauth2AuthorizationCode:
      title: OAuth2 Authorization Code
      type: object
      properties:
        accessToken:
          type: object
          required:
          - token
          description: The access token for the connection.
          properties:
            token:
              type: string
            expiresAt:
              type: string
              format: date-time
            issuedAt:
              type: string
              format: date-time
        refreshToken:
          type: object
          required:
          - token
          description: The refresh token to use for the connection.
          properties:
            token:
              type: string
            expiresAt:
              type: string
              format: date-time
            issuedAt:
              type: string
              format: date-time
        scopes:
          type: array
          items:
            type: string
          description: The scopes for the tokens.
    ProviderMetadata:
      title: Provider Metadata
      type: object
      additionalProperties:
        $ref: '#/components/schemas/ProviderMetadataInfo'
    ConnectionRequest:
      title: Connection Request Body
      type: object
      properties:
        providerWorkspaceRef:
          type: string
          description: The ID of the provider workspace that this connection belongs to.
        providerMetadata:
          $ref: '#/components/schemas/ProviderMetadata'
        groupName:
          type: string
          description: The name of the user group that has access to this installation.
        groupRef:
          type: string
          description: The ID of the user group that has access to this installation.
          example: group-123
        consumerName:
          type: string
          description: The name of the consumer that has access to this installation.
        consumerRef:
          type: string
          description: The consumer reference.
        provider:
          type: string
          description: The provider name (e.g. "salesforce", "hubspot")
        apiKey:
          type: string
          description: The API key to use for the connection.
        customAuth:
          type: object
          description: Values used for custom auth input variables.
          additionalProperties:
            type: string
            nullable: false
          example:
            apiKey: abcd1234
            password: secret
        basicAuth:
          type: object
          required:
          - username
          - password
          properties:
            username:
              type: string
              description: The username to use for the connection.
            password:
              type: string
              description: The password to use for the connection.
        oauth2ClientCredentials:
          type: object
          required:
          - clientId
          - clientSecret
          properties:
            clientId:
              type: string
              description: The client ID to use for the connection.
            clientSecret:
              type: string
              description: The client secret to use for the connection.
            scopes:
              type: array
              items:
                type: string
              description: The scopes for the tokens.
        oauth2PasswordCredentials:
          type: object
          required:
          - username
          - password
          - clientId
          - clientSecret
          properties:
            username:
              type: string
              description: The username to use for the connection.
            password:
              type: string
              description: The password to use for the connection.
            clientId:
              type: string
              description: The client ID to use for the connection.
            clientSecret:
              type: string
              description: The client secret to use for the connection.
            scopes:
              type: array
              items:
                type: string
              description: The scopes for the tokens.
        oauth2AuthorizationCode:
          $ref: '#/components/schemas/Oauth2AuthorizationCode'
    Oauth2AuthorizationCodeTokensOnly:
      title: OAuth2 AuthorizationCode Token
      type: object
      properties:
        accessToken:
          type: object
          required:
          - token
          description: The access token for the connection.
          properties:
            token:
              type: string
            issuedAt:
              type: string
              format: date-time
              example: '2024-04-22T18:55:28.456076Z'
            expiresAt:
              type: string
              format: date-time
              example: '2024-10-22T18:55:28.456076Z'
        refreshToken:
          type: object
          required:
          - token
          description: The refresh token to use for the connection.
          properties:
            token:
              type: string
            issuedAt:
              type: string
              format: date-time
              example: '2024-04-22T18:55:28.456076Z'
            expiresAt:
              type: string
              format: date-time
              example: '2024-10-22T18:55:28.456076Z'
        scopes:
          type: array
          items:
            type: string
          description: The scopes for the tokens.
    Connection:
      title: Connection
      required:
      - id
      - createTime
      - group
      - consumer
      - projectId
      - provider
      - authScheme
      - status
      type: object
      properties:
        id:
          type: string
          description: The connection ID.
          example: connection-123
        projectId:
          type: string
          description: The Ampersand project ID.
          example: project-456
        provider:
          type: string
          description: The SaaS provider that this Connection is for.
          example: salesforce
        providerApp:
          $ref: '#/components/schemas/ProviderApp'
        group:
          $ref: '#/components/schemas/Group'
        consumer:
          $ref: '#/components/schemas/Consumer'
        providerWorkspaceRef:
          type: string
          description: If available, the identifier for the provider workspace (e.g. the Salesforce subdomain)
          example: provider-workspace-123
        providerConsumerRef:
          type: string
          description: If available, the ID that Salesforce/Hubspot uses to identify this user (e.g. Salesforce has IDs in the form of https://login.salesforce.com/id/00D4x0000019CQTEA2/0054x000000orJ4AA)
          example: provider-consumer-123
        createTime:
          type: string
          description: The time the connection was created.
          format: date-time
          example: 2023-07-13 21:34:44.816354+00:00
        updateTime:
          type: string
          description: The time the connection was last updated.
          format: date-time
          example: 2023-07-13 21:34:44.816354+00:00
        authScheme:
          type: string
          description: The authentication scheme used for this connection.
          example: oauth2/authorizationCode
          enum:
          - none
          - apiKey
          - basic
          - oauth2/authorizationCode
          - oauth2/authorizationCodePKCE
          - oauth2/clientCredentials
          - oauth2/password
        status:
          type: string
          description: 'The status of the connection.

            - `created`: The connection has just been created or the access token was just refreshed.

            - `working`: The connection has successfully been used to make a request.

            - `bad_credentials`: The connection encountered credential-related issues when making a request, or when attempting to refresh the access token.

            '
          example: working
          enum:
          - created
          - working
          - bad_credentials
        oauth2AuthorizationCode:
          $ref: '#/components/schemas/Oauth2AuthorizationCodeTokensOnly'
        apiKey:
          type: string
          description: The API key used while making the connection.
          example: api-key-123
        providerMetadata:
          $ref: '#/components/schemas/ProviderMetadata'
    UpdateConnectionRequest:
      title: Update Connection Request
      description: Specify which fields to update in `updateMask` and provide corresponding values in `connection`. Fields in `connection` not listed in `updateMask` are ignored.
      type: object
      required:
      - updateMask
      - connection
      properties:
        updateMask:
          type: array
          items:
            type: string
            enum:
            - providerWorkspaceRef
            - providerMetadata
            - apiKey
            - basicAuth
            - oauth2ClientCredentials
            - oauth2PasswordCredentials
          description: Fields to update. Each entry must have a corresponding value in `connection`. Credential fields (`apiKey`, `basicAuth`, `oauth2ClientCredentials`, `oauth2PasswordCredentials`) must match the connection's existing auth scheme.
          example:
          - apiKey
        connection:
          $ref: '#/components/schemas/ConnectionRequest'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      name: X-Api-Key
      in: header
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT