Authentication

Overview

The Reelevant API uses OAuth 2.0 for authentication. Four grant types are supported:

Grant Type	Use Case
`authorization_code`	Browser-based login with PKCE (recommended for web apps)
`password`	Direct username/password exchange for legacy service accounts and scripts
`refresh_token`	Renew an expired access token without re-authenticating
`client_credentials`	Machine-to-machine integration using a service account

All token operations use the endpoint POST https://api.reelevant.com/v2/auth/token. A client_id is required for every grant. For client_credentials, HTTP Basic can supply it instead of the request body. Contact [email protected] to obtain one.

Authorization Code Flow (PKCE)

This is the recommended flow for web applications. It uses a browser redirect to authenticate the user, then exchanges an authorization code for tokens.

Step 1: Generate PKCE Challenge

Generate a random code_verifier and derive the code_challenge:

import { randomBytes, createHash } from 'crypto'

const codeVerifier = randomBytes(32).toString('base64url')
const codeChallenge = createHash('sha256')
  .update(codeVerifier)
  .digest('base64url')

Step 2: Redirect to Authorize

Redirect the user’s browser to the authorization endpoint:

GET https://api.reelevant.com/v2/oauth/authorize
  ?client_id=<client_id>
  &redirect_uri=<redirect_uri>
  &response_type=code
  &code_challenge=<code_challenge>
  &code_challenge_method=S256
  &state=<random_state>
  &lang=en

Parameter	Required	Description
`client_id`	Yes	Your OAuth client identifier
`redirect_uri`	Yes	Must match a registered redirect URI for the client
`response_type`	Yes	Must be `code` for the authorization code flow
`code_challenge`	Yes	Base64url-encoded SHA-256 hash of the `code_verifier`
`code_challenge_method`	No	Only `S256` is supported (default)
`state`	Recommended	Opaque value to prevent CSRF — returned unchanged in the callback
`lang`	No	Login page language (`en` or `fr`)

The user sees a login page. After successful authentication, a consent screen is shown. Upon approval, the browser is redirected to your redirect_uri with an authorization code:

https://your-app.com/callback?code=<authorization_code>&state=<state>

Authorization codes are single-use and expire after 60 seconds. Exchange them immediately.

Step 3: Exchange Code for Tokens

curl -XPOST https://api.reelevant.com/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "<client_id>",
    "grant_type": "authorization_code",
    "code": "<authorization_code>",
    "redirect_uri": "<redirect_uri>",
    "code_verifier": "<code_verifier>"
  }'

The code_verifier must match the code_challenge sent in Step 2 (the server verifies SHA256(code_verifier) == code_challenge). Response:

{
  "access_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "refresh_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Some OAuth clients are configured with requireAuthorizationCodeFlow: true. For these clients, PKCE parameters are mandatory — the implicit flow is disabled entirely.

Password Grant

For service accounts and automation scripts where browser-based login is not practical.

curl -XPOST https://api.reelevant.com/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "your-password",
    "grant_type": "password",
    "client_id": "<client_id>"
  }'

Response:

{
  "access_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "refresh_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Two-Factor Authentication (OTP)

If the user has OTP enabled, include the x-otp-code field:

curl -XPOST https://api.reelevant.com/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "your-password",
    "grant_type": "password",
    "client_id": "<client_id>",
    "x-otp-code": "123456"
  }'

Refresh Token Grant

Exchange a valid refresh token for a new access token without re-authenticating:

curl -XPOST https://api.reelevant.com/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "grant_type": "refresh_token",
    "client_id": "<client_id>"
  }'

Response:

{
  "access_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "refresh_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Client Credentials Grant (Service Accounts)

type ClientCredentialsResponse = {
  access_token: string
  expires_in: number
  token_type: 'Bearer'
}

const isClientCredentialsResponse = (value: unknown): value is ClientCredentialsResponse =>
  typeof value === 'object' &&
  value !== null &&
  'access_token' in value &&
  typeof value.access_token === 'string' &&
  'expires_in' in value &&
  typeof value.expires_in === 'number' &&
  'token_type' in value &&
  value.token_type === 'Bearer'

const gatewayUrl = process.env.REELEVANT_GATEWAY_URL ?? 'https://api.reelevant.com'
const clientId = process.env.REELEVANT_CLIENT_ID
const clientSecret = process.env.REELEVANT_CLIENT_SECRET

if (!clientId || !clientSecret) {
  throw new Error('Set REELEVANT_CLIENT_ID and REELEVANT_CLIENT_SECRET')
}

let cachedToken: { accessToken: string; expiresAt: number } | undefined
let pendingToken: Promise<string> | undefined

export const getAccessToken = async (): Promise<string> => {
  if (cachedToken && Date.now() < cachedToken.expiresAt) {
    return cachedToken.accessToken
  }

  const request =
    pendingToken ??
    (pendingToken = (async () => {
      const requestedAt = Date.now()
      const response = await fetch(`${gatewayUrl}/v2/auth/token`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          grant_type: 'client_credentials',
          client_id: clientId,
          client_secret: clientSecret,
        }),
      })

      if (!response.ok) {
        throw new Error(`Token request failed: ${response.status} ${await response.text()}`)
      }

      const body: unknown = await response.json()
      if (!isClientCredentialsResponse(body)) {
        throw new Error('The token endpoint returned an invalid response')
      }

      cachedToken = {
        accessToken: body.access_token,
        expiresAt: requestedAt + Math.max(0, (body.expires_in - 60) * 1000),
      }

      return cachedToken.accessToken
    })())

  try {
    return await request
  } finally {
    if (pendingToken === request) {
      pendingToken = undefined
    }
  }
}

Set REELEVANT_CLIENT_ID and REELEVANT_CLIENT_SECRET in the integration environment. Keep the secret outside source control. This example caches the access token in memory and requests another one 60 seconds before expiry. A service account and its client secret are created by an admin; see the service account guide. Send grant_type=client_credentials, client_id, and client_secret as JSON or application/x-www-form-urlencoded. You can instead send the credentials in an HTTP Basic header:

curl --user "$REELEVANT_CLIENT_ID:$REELEVANT_CLIENT_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  https://api.reelevant.com/v2/auth/token

Load these values from a secrets manager or protected environment; do not type the secret into commands or shell history. When an HTTP Basic header is present, its credentials take precedence over body credentials. A malformed Basic header is rejected and does not fall back to the body.

Parameter	Type	Required	Default	Description
`grant_type`	string	Yes	—	Must be `client_credentials`.
`client_id`	string	Yes, unless supplied by HTTP Basic	—	The service account identifier.
`client_secret`	string	Yes, unless supplied by HTTP Basic	—	The client secret, shown only once when created.

Response:

{
  "access_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "expires_in": 3600,
  "token_type": "Bearer"
}

The response does not include a refresh_token. Access tokens expire after one hour; request another token with the client credentials when needed. Successful responses include Cache-Control: no-store and Pragma: no-cache. Up to two client secrets can be active at once, allowing rotation. Revoking a secret also revokes access tokens issued with that secret. Disabling the service account immediately blocks new grants and invalidates its existing access tokens.

Using Access Tokens

Include the access token in every API request via the Authorization header:

Authorization: Bearer <access_token>

Token Lifecycle

Token Type	Lifetime	Renewal
Access token	1 hour	Use `refresh_token` grant to obtain a new one
Client-credentials access token	1 hour	Request a new token; no `refresh_token` is issued
Refresh token	30 days (rolling)	Refreshed automatically each time it is used to generate a new access token
Authorization code	60 seconds	Single-use — exchange immediately after receiving

Refresh tokens use a rolling expiry: the 30-day window resets each time you use the refresh token. If you refresh at least once a month, the token never expires.

Revoking Tokens

Revoke an access token or refresh token:

curl -XDELETE https://api.reelevant.com/v2/auth/token/<token_id>

Revoking a refresh token also revokes all access tokens derived from it. Revoking a client secret also revokes access tokens issued with that secret. Disabling its service account invalidates all of its access tokens.

SCIM Provisioning

Inbound provisioning uses company-scoped bearer tokens instead of OAuth user tokens. See SCIM 2.0 provisioning.

SSO Authentication

Companies with SSO configured are automatically redirected to their identity provider during the OAuth authorize flow. If SSO is mandatory for the company, password-based login is disabled (except for service accounts).

Error Handling

Error	HTTP Status	Cause
`invalid_client`	400	Unknown or inactive `client_id`
`invalid_redirect_uri`	400	`redirect_uri` not in the client’s allowed list
`invalid_request`	400	Missing required parameters (e.g., `code_challenge` for PKCE)
`invalid_credentials`	401	Wrong username or password
`too_many_attempts`	429	Login attempts exceeded — wait before retrying
`password_expired`	401	Password must be changed before logging in
`otp_required`	401	OTP code required but not provided
`invalid_code`	400	Authorization code is invalid, expired, or already used
`pkce_mismatch`	400	`code_verifier` does not match the original `code_challenge`
`InvalidClientCredentials`	401 (5512)	Client ID or secret is invalid, revoked, or does not belong to a service account
`ClientSecretLimitReached`	409 (5310)	Creating a third active client secret

A disabled service account returns UserDisabled.

Service accounts

Create service accounts and manage their client secrets.

Authentication & SSO

Review platform authentication options and integration patterns.

Getting Started

SDKs

Data Collection

Web Integration

Mobile Integration

Guides

Datasources API

Contents API

Workflow API

Datasources Collector

Entity Manager API

Statistics API

Overview

Authorization Code Flow (PKCE)

Step 1: Generate PKCE Challenge

Step 2: Redirect to Authorize

Step 3: Exchange Code for Tokens

Password Grant

Two-Factor Authentication (OTP)

Refresh Token Grant

Client Credentials Grant (Service Accounts)

Using Access Tokens

Token Lifecycle

Revoking Tokens

SCIM Provisioning

SSO Authentication

Error Handling

Service accounts

Authentication & SSO

​Overview

​Authorization Code Flow (PKCE)

​Step 1: Generate PKCE Challenge

​Step 2: Redirect to Authorize

​Step 3: Exchange Code for Tokens

​Password Grant

​Two-Factor Authentication (OTP)

​Refresh Token Grant

​Client Credentials Grant (Service Accounts)

​Using Access Tokens

​Token Lifecycle

​Revoking Tokens

​SCIM Provisioning

​SSO Authentication

​Error Handling

​Related

Service accounts

Authentication & SSO

Overview

Authorization Code Flow (PKCE)

Step 1: Generate PKCE Challenge

Step 2: Redirect to Authorize

Step 3: Exchange Code for Tokens

Password Grant

Two-Factor Authentication (OTP)

Refresh Token Grant

Client Credentials Grant (Service Accounts)

Using Access Tokens

Token Lifecycle

Revoking Tokens

SCIM Provisioning

SSO Authentication

Error Handling

Related