Skip to main content
POST
/
oauth-connect
curl --request POST \
  --url https://api.withampersand.com/v1/oauth-connect \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "projectId": "my-project",
  "provider": "salesforce",
  "groupRef": "group-123",
  "consumerRef": "user_123456"
}
'
"https://login.salesforce.com/services/oauth2/authorize?client_id=xxx&redirect_uri=https%3A%2F%2Fapi.withampersand.com%2Fcallbacks%2Fv1%2Foauth&state=xxx"

Authorizations

​
X-Api-Key
string
header
required

Body

application/json
​
projectId
string
required

The Ampersand project ID.

Example:

"my-project"

​
provider
string
required

The provider that this app connects to.

Example:

"salesforce"

​
groupRef
string
required

Your application's identifier for the organization or workspace that this connection belongs to (e.g. an org ID or team ID).

Example:

"group-123"

​
consumerRef
string
required

The ID that your app uses to identify the user whose SaaS credential will be used for this OAuth flow.

Example:

"user_123456"

​
groupName
string

The display name for the group. Defaults to groupRef if not provided.

Example:

"Organization Name"

​
consumerName
string

The display name for the consumer. Defaults to consumerRef if not provided.

Example:

"John Doe"

​
providerWorkspaceRef
string

The identifier for the provider workspace (e.g. the Salesforce subdomain).

Example:

"acme-corp"

​
providerMetadata
Provider Metadata · object

Additional provider-specific metadata required by certain providers (e.g., account ID for NetSuite). See provider documentation for which fields are needed.

Example:
{
  "accountId": { "value": "1234567890", "source": "input" }
}
​
providerAppId
string

ID of the provider app, returned from the Create Provider App endpoint. If omitted, the default provider app that was set up on the Ampersand Dashboard is assumed.

Example:

"32356abe-d2fd-49c7-9030-abdcbc6456d4"

​
enableCSRFProtection
boolean

This boolean flag is used by the UI library internally. Set it to false or omit it when manually calling this API.

Example:

false

Response

OK

URL to render

Example:

"https://login.salesforce.com/services/oauth2/authorize?client_id=xxx&redirect_uri=https%3A%2F%2Fapi.withampersand.com%2Fcallbacks%2Fv1%2Foauth&state=xxx"