> ## Documentation Index > Fetch the complete documentation index at: https://docs.withampersand.com/llms.txt > Use this file to discover all available pages before exploring further. # List connections ## OpenAPI ````yaml platform get /projects/{projectIdOrName}/connections openapi: 3.0.1 info: title: Ampersand public API version: 1.0.0 servers: - url: https://api.withampersand.com/v1 security: - APIKeyHeader: [] - Bearer: [] paths: /projects/{projectIdOrName}/connections: get: tags: - Connection summary: List connections operationId: listConnections 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: 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: 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: 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 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 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-13T21:34:44.816Z' updateTime: type: string description: The time the group was last updated. format: date-time example: '2023-07-13T21:34:44.816Z' 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-13T21:34:44.816Z' updateTime: type: string description: The time the consumer was last updated. format: date-time example: '2023-07-13T21:34:44.816Z' 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-13T21:34:44.816Z' updateTime: type: string description: The time the connection was last updated. format: date-time example: '2023-07-13T21:34:44.816Z' 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: 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. apiKey: type: string description: The API key used while making the connection. example: api-key-123 providerMetadata: title: Provider Metadata type: object additionalProperties: 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 '404': description: Not Found content: application/problem+json: schema: title: Input Validation Problem type: object allOf: - title: API Problem type: object allOf: - title: Problem description: > A Problem Details object (RFC 9457). Additional properties specific to the problem type may be present. type: object properties: type: type: string format: uri description: An absolute URI that identifies the problem type default: about:blank href: type: string format: uri description: >- An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML). title: type: string description: >- A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized). example: Service Unavailable status: type: integer format: int32 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 400 maximum: 600 exclusiveMaximum: true example: 503 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem instance: type: string format: uri description: >- An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: type: urn:problem-type:exampleOrganization:exampleProblem href: >- https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types title: Description of the type of problem that occurred status: 400 detail: Description of specific occurrence of the problem instance: urn:uuid:123e4567-e89b-12d3-a456-426614174000 properties: subsystem: type: string description: The subsystem that generated the problem example: api time: type: string format: date-time description: The time the problem occurred, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' requestId: type: string description: >- A unique identifier for the request, useful for debugging example: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715 causes: type: array items: type: string description: >- A brief description of something which caused the problem example: database connection failed example: - database connection failed - database query failed - unable to fetch user description: > A list of problems that caused this problem. This can be used to represent multiple root causes. There is no guaranteed ordering of the causes. remedy: type: string description: A brief description of how to resolve the problem example: Shorten your input to be under 100 characters supportEmail: type: string format: email description: An email address to contact for support example: support@withampersand.com supportPhone: type: string description: A phone number to contact for support example: +1-555-555-5555 supportUrl: type: string format: uri description: A URL to contact for support example: https://withampersand.com/support retryable: type: boolean description: Whether the request can be retried example: false retryAfter: type: string format: date-time description: >- A timestamp after which the request can be retried, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' context: type: object description: Additional context for the problem additionalProperties: true example: name: Rick Sanchez properties: issues: type: array items: title: Input Validation Issue type: object description: | An issue detected during input validation. allOf: - title: API Problem type: object allOf: - title: Problem description: > A Problem Details object (RFC 9457). Additional properties specific to the problem type may be present. type: object properties: type: type: string format: uri description: >- An absolute URI that identifies the problem type default: about:blank href: type: string format: uri description: >- An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML). title: type: string description: >- A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized). example: Service Unavailable status: type: integer format: int32 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 400 maximum: 600 exclusiveMaximum: true example: 503 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem instance: type: string format: uri description: >- An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: type: >- urn:problem-type:exampleOrganization:exampleProblem href: >- https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types title: >- Description of the type of problem that occurred status: 400 detail: >- Description of specific occurrence of the problem instance: urn:uuid:123e4567-e89b-12d3-a456-426614174000 properties: subsystem: type: string description: The subsystem that generated the problem example: api time: type: string format: date-time description: >- The time the problem occurred, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' requestId: type: string description: >- A unique identifier for the request, useful for debugging example: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715 causes: type: array items: type: string description: >- A brief description of something which caused the problem example: database connection failed example: - database connection failed - database query failed - unable to fetch user description: > A list of problems that caused this problem. This can be used to represent multiple root causes. There is no guaranteed ordering of the causes. remedy: type: string description: >- A brief description of how to resolve the problem example: Shorten your input to be under 100 characters supportEmail: type: string format: email description: An email address to contact for support example: support@withampersand.com supportPhone: type: string description: A phone number to contact for support example: +1-555-555-5555 supportUrl: type: string format: uri description: A URL to contact for support example: https://withampersand.com/support retryable: type: boolean description: Whether the request can be retried example: false retryAfter: type: string format: date-time description: >- A timestamp after which the request can be retried, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' context: type: object description: Additional context for the problem additionalProperties: true example: name: Rick Sanchez properties: in: type: string description: The location of the invalid input enum: - body - header - path - query name: type: string description: The name of the invalid input value: description: The value of the erroneous input example: type: about:blank title: Bad Request status: 400 detail: The input message is incorrect instance: 123456-1234-1235-4567489798 issues: - type: about:blank detail: exampleNumericProperty should be numeric in: path name: exampleNumericProperty value: abc - type: about:blank title: Input isn't valid with respect to schema detail: >- examplePropertyWithPattern a2345678901 doesn't match pattern '^\d{11}$' in: body name: items[0].examplePropertyWithPattern value: a2345678901 default: description: Error content: application/problem+json: schema: title: API Problem type: object allOf: - title: Problem description: > A Problem Details object (RFC 9457). Additional properties specific to the problem type may be present. type: object properties: type: type: string format: uri description: An absolute URI that identifies the problem type default: about:blank href: type: string format: uri description: >- An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML). title: type: string description: >- A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized). example: Service Unavailable status: type: integer format: int32 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 400 maximum: 600 exclusiveMaximum: true example: 503 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem instance: type: string format: uri description: >- An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: type: urn:problem-type:exampleOrganization:exampleProblem href: >- https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types title: Description of the type of problem that occurred status: 400 detail: Description of specific occurrence of the problem instance: urn:uuid:123e4567-e89b-12d3-a456-426614174000 properties: subsystem: type: string description: The subsystem that generated the problem example: api time: type: string format: date-time description: The time the problem occurred, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' requestId: type: string description: A unique identifier for the request, useful for debugging example: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715 causes: type: array items: type: string description: >- A brief description of something which caused the problem example: database connection failed example: - database connection failed - database query failed - unable to fetch user description: > A list of problems that caused this problem. This can be used to represent multiple root causes. There is no guaranteed ordering of the causes. remedy: type: string description: A brief description of how to resolve the problem example: Shorten your input to be under 100 characters supportEmail: type: string format: email description: An email address to contact for support example: support@withampersand.com supportPhone: type: string description: A phone number to contact for support example: +1-555-555-5555 supportUrl: type: string format: uri description: A URL to contact for support example: https://withampersand.com/support retryable: type: boolean description: Whether the request can be retried example: false retryAfter: type: string format: date-time description: >- A timestamp after which the request can be retried, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' context: type: object description: Additional context for the problem additionalProperties: true example: name: Rick Sanchez components: securitySchemes: APIKeyHeader: type: apiKey name: X-Api-Key in: header Bearer: type: http scheme: bearer bearerFormat: JWT ````