Skip to main content
GET
/
projects
/
{projectIdOrName}
/
connections
/
{connectionId}
Get a connection
curl --request GET \
  --url https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId} \
  --header 'X-Api-Key: <api-key>'
{
  "id": "connection-123",
  "projectId": "project-456",
  "provider": "salesforce",
  "providerApp": {
    "id": "provider-app-123",
    "projectId": "project-456",
    "externalRef": "external-id-123",
    "provider": "salesforce",
    "clientId": "client-id-123",
    "scopes": [
      [
        "oauth",
        "offline",
        "crm.read"
      ]
    ],
    "createTime": "2023-11-07T05:31:56Z",
    "updateTime": "2023-11-07T05:31:56Z"
  },
  "group": {
    "groupRef": "group-123",
    "groupName": "Super Customer",
    "projectId": "project-456",
    "createTime": "2023-07-13T21:34:44.816Z",
    "updateTime": "2023-07-13T21:34:44.816Z"
  },
  "consumer": {
    "consumerRef": "consumer-123",
    "consumerName": "Super Customer",
    "projectId": "project-456",
    "createTime": "2023-07-13T21:34:44.816Z",
    "updateTime": "2023-07-13T21:34:44.816Z"
  },
  "providerWorkspaceRef": "provider-workspace-123",
  "providerConsumerRef": "provider-consumer-123",
  "createTime": "2023-07-13T21:34:44.816Z",
  "updateTime": "2023-07-13T21:34:44.816Z",
  "authScheme": "oauth2/authorizationCode",
  "status": "working",
  "oauth2AuthorizationCode": {
    "accessToken": {
      "token": "<string>",
      "issuedAt": "2024-04-22T18:55:28.456076Z",
      "expiresAt": "2024-10-22T18:55:28.456076Z"
    },
    "refreshToken": {
      "token": "<string>",
      "issuedAt": "2024-04-22T18:55:28.456076Z",
      "expiresAt": "2024-10-22T18:55:28.456076Z"
    },
    "scopes": [
      "<string>"
    ]
  },
  "apiKey": "api-key-123",
  "providerMetadata": {}
}

Authorizations

​
X-Api-Key
string
header
required

Path Parameters

​
projectIdOrName
string
required

The Ampersand project ID or project name.

​
connectionId
string
required

Query Parameters

​
includeCreds
boolean

Whether to include the credentials in the response. Only access token will be included. Default is false.

​
includeRefreshToken
boolean

Whether to include the refresh token in credentials in the response along with access token. If true, the includeCreds query parameter will be ignored. Default is false.

​
refresh
enum<string>

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.

Available options:
force,
ifExpired

Response

Connection

​
id
string
required

The connection ID.

Example:

"connection-123"

​
projectId
string
required

The Ampersand project ID.

Example:

"project-456"

​
provider
string
required

The SaaS provider that this Connection is for.

Example:

"salesforce"

​
group
object
required
​
consumer
object
required
​
createTime
string<date-time>
required

The time the connection was created.

Example:

"2023-07-13T21:34:44.816Z"

​
authScheme
enum<string>
required

The authentication scheme used for this connection.

Available options:
none,
apiKey,
basic,
oauth2/authorizationCode,
oauth2/authorizationCodePKCE,
oauth2/clientCredentials,
oauth2/password
Example:

"oauth2/authorizationCode"

​
status
enum<string>
required

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.
Available options:
created,
working,
bad_credentials
Example:

"working"

​
providerApp
object
​
providerWorkspaceRef
string

If available, the identifier for the provider workspace (e.g. the Salesforce subdomain)

Example:

"provider-workspace-123"

​
providerConsumerRef
string

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"

​
updateTime
string<date-time>

The time the connection was last updated.

Example:

"2023-07-13T21:34:44.816Z"

​
oauth2AuthorizationCode
object
​
apiKey
string

The API key used while making the connection.

Example:

"api-key-123"

​
providerMetadata
object
⌘I