Skip to main content
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

1

Create an OAuth connection

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

Choose scopes

Under Scopes, check the Public API version your app calls: Public API v1 (publicAPI.v1.all) or Public API v2 (publicAPI.v2.all). Tokens from the connection can only call the versions you check. v2 is in beta and returns 403 until Seamless enables it for your organization.
3

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

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

Example response:
By default, access tokens expire after 180 minutes and refresh tokens after 7 days without a refresh; each refresh resets that window. Always schedule renewals from expires_at and refresh_token_expires_at in the response rather than from these defaults. Parameter reference: Get an access token.

3. Call the API with the access token

4. Refresh an expired token

The response has the same shape as the code exchange. The refresh token may be rotated, so always store the refresh_token from the latest response.

Next steps