> ## 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.

# Auth

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](/management-api/credentials/create) or [create a sync](/management-api/syncs/create).
2. **Sequin OAuth2**: Alternatively, you can use Sequin's OAuth2 flow to authenticate your customers.

## Sequin OAuth2

Sequin offers an [OAuth2](https://oauth.net/2/) 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:

```bash theme={null}
# Sequin's redirect_uri
https://auth-gateway.sequin.io/link/oauth2/callback/:provider
```

`:provider` is the [slug of the provider](/management-api/objects#sync-providers) (e.g. `stripe` or `salesforce`). This is where the API provider should send your customers after they've approved the connection.

<Note>
  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.
</Note>

### 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:

```bash theme={null}
https://example.com/oauth2/callback/:provider
```

And the provider slug is `stripe`, Sequin will redirect your customers to:

```bash theme={null}
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:

```bash theme={null}
https://auth-gateway.sequin.io/link/oauth2/start
```

For example:

```bash theme={null}
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
```

<ParamField query="client_id" type="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.
</ParamField>

<ParamField query="redirect_uri" type="string" required>
  The redirect URI you registered in the Sequin console.
</ParamField>

<ParamField query="state" type="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.
</ParamField>

<ParamField query="scope" type="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.
</ParamField>

<ParamField query="debug" type="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.
</ParamField>

<Info>
  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.
</Info>

### 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:

```bash theme={null}
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](/auth/token).

### 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.