> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seamless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.0

> Register an OAuth client, obtain access and refresh tokens, and call the Seamless API with Bearer authentication.

Use OAuth when your product signs users in with Seamless and acts on their behalf. Each user gets their own access token; your backend stores refresh tokens securely.

<Note>
  API keys use the `Token` header. OAuth access tokens use `Authorization: Bearer`. Do not mix them on the same request.
</Note>

## Register your application

<Steps>
  <Step title="Create an OAuth connection">
    Go to [Settings → Public API](https://login.seamless.ai/settings/public-api), open **OAuth Connections**, and click **Create New Connection**.
  </Step>

  <Step title="Save client credentials">
    Record `client_id`, `client_secret`, and `redirect_uri`. You need all three for token exchange and refresh.
  </Step>
</Steps>

## Authorization code flow

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Browser as User browser
  participant Seamless as Seamless login
  participant API as Seamless API
  App->>Browser: Redirect to authorize URL
  Browser->>Seamless: GET /oauth/authorize
  Seamless->>Browser: Redirect with ?code=
  Browser->>App: Callback with code
  App->>API: POST /oauth/accessToken
  API-->>App: access_token, refresh_token
  App->>API: API calls with Bearer token
```

### 1. Redirect the user to authorize

```text theme={null}
GET https://login.seamless.ai/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&state=RANDOM_CSRF_STRING
```

| Query param    | Description                                            |
| -------------- | ------------------------------------------------------ |
| `client_id`    | Your client ID                                         |
| `redirect_uri` | Must match the URI registered on the connection        |
| `state`        | Optional CSRF protection string you verify on callback |

If `redirect_uri` includes query parameters, URL-encode the full URI when building this link.

After the user signs in, Seamless redirects to your `redirect_uri` with a `code` query parameter.

### 2. Exchange the code for tokens

```bash theme={null}
curl -X POST "https://api.seamless.ai/api/client/v1/oauth/accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://yourapp.com/callback",
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE_FROM_CALLBACK"
  }'
```

Example response:

```json theme={null}
{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_at": 1712000000
}
```

Parameter reference: [Get an access token](/reference/getaccesstoken).

### 3. Call the API with the access token

```bash theme={null}
curl -X POST "https://api.seamless.ai/api/client/v1/search/contacts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"jobTitle": ["VP Sales"], "limit": 5}'
```

### 4. Refresh an expired token

```bash theme={null}
curl -X POST "https://api.seamless.ai/api/client/v1/oauth/accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://yourapp.com/callback",
    "grant_type": "refresh_token",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'
```

## Next steps

* [First API request](/authenticate-and-make-your-first-request) — runnable search → research → poll flow
* [Rate limits & credits](/rate-limits-and-credits) — headers on every response
* [Troubleshooting](/troubleshoot-authentication-and-request-failures) — 401 and token issues