POST
/
projects
/
{projectIdOrName}
/
connections:generate
Generate a new connection
curl --request POST \
  --url https://api.withampersand.com/v1/projects/{projectIdOrName}/connections:generate \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "providerWorkspaceRef": "<string>",
  "providerMetadata": {},
  "groupName": "<string>",
  "groupRef": "group-123",
  "consumerName": "<string>",
  "consumerRef": "<string>",
  "provider": "<string>",
  "apiKey": "<string>",
  "customAuth": {
    "apiKey": "abcd1234",
    "password": "secret"
  },
  "basicAuth": {
    "username": "<string>",
    "password": "<string>"
  },
  "oauth2ClientCredentials": {
    "clientId": "<string>",
    "clientSecret": "<string>",
    "scopes": [
      "<string>"
    ]
  },
  "oauth2PasswordCredentials": {
    "username": "<string>",
    "password": "<string>",
    "clientId": "<string>",
    "clientSecret": "<string>",
    "scopes": [
      "<string>"
    ]
  },
  "oauth2AuthorizationCode": {
    "accessToken": {
      "token": "<string>",
      "expiresAt": "2023-11-07T05:31:56Z",
      "issuedAt": "2023-11-07T05:31:56Z"
    },
    "refreshToken": {
      "token": "<string>",
      "expiresAt": "2023-11-07T05:31:56Z",
      "issuedAt": "2023-11-07T05:31:56Z"
    },
    "scopes": [
      "<string>"
    ]
  }
}'
{
  "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.

Body

application/json
groupRef
string
required

The ID of the user group that has access to this installation.

Example:

"group-123"

consumerRef
string
required

The consumer reference.

provider
string
required

The provider name (e.g. "salesforce", "hubspot")

providerWorkspaceRef
string

The ID of the provider workspace that this connection belongs to.

providerMetadata
object
groupName
string

The name of the user group that has access to this installation.

consumerName
string

The name of the consumer that has access to this installation.

apiKey
string

The API key to use for the connection.

customAuth
object

Values used for custom auth input variables.

Example:
{
"apiKey": "abcd1234",
"password": "secret"
}
basicAuth
object
oauth2ClientCredentials
object
oauth2PasswordCredentials
object
oauth2AuthorizationCode
object

Response

Created

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.

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