Generate OAuth authorization URL - Ampersand

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"
}
'

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

{
  "type": "about:blank",
  "href": "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types",
  "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"
    }
  ]
}

{
  "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"
}

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 '
{
  "projectIdOrName": "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"

{
  "type": "about:blank",
  "href": "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types",
  "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"
    }
  ]
}

{
  "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"
}

Authorizations

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

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"