POST
/
v1
/
credentials
/
start-auth
curl --request POST \
  --url https://api.sequin.io/v1/credentials/start-auth \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "oauth_app_id": "8ff58ef0-d376-4ae8-b2e2-9f0206aa65b8",
    "credential_kind": "salesforce_oauth2",
    "redirect_url": "https://acme.corp/oauth-finish",
    "state": {
      "user_id": "4e6be1b3-5bc4-4336-b97d-e243a5507dc0"
    }
  }'
{
  "start_url": "https://api.sequin.io/link/oauth2/start/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
}

Flow

  1. Your app makes a POST request to this endpoint.
  2. Sequin returns a secure, expiring link.
  3. Your frontend redirects the user to the link.
  4. Sequin walks the user through the OAuth flow with the upstream provider (e.g. Salesforce or Stripe).
  5. Sequin redirects the user back to your app with a code.
  6. Your app makes a POST request to the exchange-code endpoint to retrieve the user’s credentials.
  7. Your app makes a POST request to create a credential or a sync with the user’s credentials.
oauth_app_id
string
required

OAuth app to use in the flow. Learn more about the OAuth app object.

credential_kind
string
required

The kind of credential to generate a link for. See the list of possible credential kinds.

redirect_url
string
required

URL to redirect the user to at the end of the flow. Sequin will redirect the user back to this URL with a code you can use to retrieve their credentials.

state
any

Any state you want Sequin to pass back to you at the end of the flow. Sequin will return this value to you when you call the exchange code endpoint.

state can be an object up to 5kb in size.

start_url
string

The secure, expiring link that you can redirect the user to. The link can be used once and expires after 5 minutes.

200 OK
{
  "start_url": "https://api.sequin.io/link/oauth2/start/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
}

End-of-flow redirect to your app

At the end of the flow, Sequin redirects the user back to the redirect_url you specified at the beginning of the flow. Sequin appends the following query parameters:

On success

success
boolean

true if the user successfully completed the OAuth flow.

code
string

The code you can use to retrieve the user’s credentials. Pass this code to the exchange-code endpoint.

?success=true&code=BTNsQNebVfaVDUwme85dAO9PgUcvxvXkEAY

On failure

success
boolean

false if the user did not complete the OAuth flow.

error_code
string

The error code for the failure. Possible values are user_canceled and provider_error.

?success=false&error=user_canceled