Skip to main content

Documentation Index

Fetch the complete documentation index at: https://sequin.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

In order to sync API data, Sequin needs credentials to authenticate with the upstream API. If you’re syncing data from your own API account, you can authenticate Sequin from the Sequin console. As you setup a sync, Sequin will guide you through the authentication process. If you’re syncing data from your customers’ API accounts, you have two options:
  1. Build your own authentication: You can build your own authentication flow. After your customer grants you their credentials, you can use Sequin’s management API to import their credentials or create a sync.
  2. Sequin OAuth2: Alternatively, you can use Sequin’s OAuth2 flow to authenticate your customers.

​
Sequin OAuth2

Sequin offers an OAuth2 flow you can use to authenticate with your customers’ API accounts. It “wraps” the authentication flows of other APIs. While OAuth2 is a standard, there are a lot of variant implementations. By using Sequin’s OAuth2 flow, you can implement OAuth2 once and gain access to dozens of APIs.

​
Setup

​
1. Register your app with the provider(s)

For each API you want to connect to, you’ll create an OAuth app on the provider’s website. The provider will generate a client_id and client_secret for your app. Because you own the OAuth app, you can control the branding of the flow. In the “redirect URI” field, you’ll enter the following URL: 
# Sequin's redirect_uri
https://auth-gateway.sequin.io/link/oauth2/callback/:provider
:provider is the slug of the provider (e.g. stripe or salesforce). This is where the API provider should send your customers after they’ve approved the connection.
Because credentials are created under your OAuth account, this also means there is no lock-in; you can always export your customers’ credentials and use them in your own system.

​
2. Add your OAuth apps and redirect URIs to Sequin

In the Sequin console, navigate to “Accounts” > “OAuth Apps.” Register your OAuth apps with Sequin by providing the client_id and client_secret for each app. You’ll also register allowed redirect URIs that apply to all OAuth apps. These are the URIs that Sequin will redirect your customers to after they’ve approved the connection. In your redirect URIs, you can use the special :provider token. Sequin will replace this token with the provider slug when redirecting your customers. For example, if you specify a redirect URI like: 
https://example.com/oauth2/callback/:provider
And the provider slug is stripe, Sequin will redirect your customers to: 
https://example.com/oauth2/callback/stripe

​
Usage

​
1. Start the OAuth flow

Start the OAuth flow by redirecting the user to Sequin’s authorize URL. The URL takes the form: 
https://auth-gateway.sequin.io/link/oauth2/start
For example: 
https://auth-gateway.sequin.io/link/oauth2/start?client_id=e097e1c7-04cf-4940-8d85-16413a158ba8&redirect_uri=https://example.com/oauth2/callback/stripe&state=ZTA5N2UxYzctMDRjZi00OTQwLThkODUtMTY0MTNhMTU4YmE4
​
client_id
string
required
The Sequin ID of the OAuth app you want to use for this connection. You can find this ID in the Sequin console.Note that this is not the client_id corresponding to the OAuth app.
​
redirect_uri
string
required
The redirect URI you registered in the Sequin console.
​
state
string
An optional string you can use to store information about the session. For example, you can store the user ID of the user initiating the OAuth flow.state will be passed back to you at the end of the OAuth flow.
​
scope
string
An optional string you can use to specify the scopes you want to use in the OAuth flow.If not specified, Sequin will specify default scopes.
​
debug
boolean
An optional boolean you can use to enable debug mode.In debug mode, Sequin will display helpful diagnostics in the browser if there’s an issue with the authorize URL.
It’s important to note that Sequin uses the Sequin ID of OAuth Apps as the client_id instead of the OAuth app’s client_id. This is to avoid possible ID collisions of client IDs across different OAuth apps.

​
2. User approves the connection

Sequin will route the user to the API provider. The user will approve the connection and the provider will redirect the user back to Sequin.

​
3. Sequin handles the token exchange

Sequin will exchange the authorization code for an access token and refresh token. Sequin will cache these tokens securely and associate them with your account.

​
4. Sequin redirects back to you

Sequin will redirect the user back to the redirect URI you provided. The redirect URI will include the code and state parameters. For example, if you set the redirect_uri to https://example.com/oauth2/callback/stripe, Sequin will redirect the user to: 
https://example.com/oauth2/callback/stripe?code=BTNsQNebVfaVDUwme85dAO9PgUcvxvXkEAY&state=ZTA5N2UxYzctMDRjZi00OTQwLThkODUtMTY0MTNhMTU4YmE4

​
5. Exchange the code for credentials

You can use the code parameter to exchange it for credentials. You can do this by making a POST request to the /link/oauth2/token endpoint. Read more about the token exchange endpoint.

​
6. Create a credential or a sync

After you’ve exchanged the code for credentials, you can use the credentials to create a credential or a sync for the user.