OAuth 2.0

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.

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

Register your application

Create an OAuth connection

Go to Settings → Public API, open OAuth Connections, and click Create New Connection.

Save client credentials

Record client_id, client_secret, and redirect_uri. You need all three for token exchange and refresh.

Authorization code flow

1. Redirect the user to authorize

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

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:

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_at": 1712000000
}

Parameter reference: Get an access token.

3. Call the API with the access token

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

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 — runnable search → research → poll flow
Rate limits & credits — headers on every response
Troubleshooting — 401 and token issues

Get Started

Core concepts

Use cases

Workflows

Guides

Troubleshooting

Register your application

Authorization code flow

1. Redirect the user to authorize

2. Exchange the code for tokens

3. Call the API with the access token

4. Refresh an expired token

Next steps

​Register your application

​Authorization code flow

​1. Redirect the user to authorize

​2. Exchange the code for tokens

​3. Call the API with the access token

​4. Refresh an expired token

​Next steps

Register your application

Authorization code flow

1. Redirect the user to authorize

2. Exchange the code for tokens

3. Call the API with the access token

4. Refresh an expired token

Next steps