Generate OAuth authorization URL

Generate a URL for the browser to render to kick off OAuth flow. You can use this endpoint as an alternative to the prebuilt UI components.

POST /oauth-connect

cURL

basicOAuth

curl --request POST \
  --url https://api.withampersand.com/v1/oauth-connect \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "projectIdOrName": "my-project",
  "provider": "salesforce",
  "groupRef": "group-123",
  "consumerRef": "user_123456"
}
'

200

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

Authorizations

APIKeyHeaderBearer

X-Api-Key · string · header · required

Body

application/json

projectIdOrName · string · required

The Ampersand project ID or project name.

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.

Show child attributes

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

200

text/plain

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"