Authentification

Vue d’ensemble

L’API Reelevant utilise OAuth 2.0 pour l’authentification. Quatre types de grant sont pris en charge :

Type de grant	Cas d’usage
`authorization_code`	Connexion via le navigateur avec PKCE (recommandé pour les applications web)
`password`	Échange direct identifiant/mot de passe pour les anciens comptes de service et les scripts
`refresh_token`	Renouveler un token d’accès expiré sans se réauthentifier
`client_credentials`	Intégration machine à machine avec un compte de service

Toutes les opérations sur les tokens utilisent l’endpoint POST https://api.reelevant.com/v2/auth/token. Un client_id est requis pour chaque grant. Pour client_credentials, l’en-tête HTTP Basic peut le fournir à la place du corps. Contactez [email protected] pour en obtenir un.

Flux Authorization Code (PKCE)

Il s’agit du flux recommandé pour les applications web. Il utilise une redirection du navigateur pour authentifier l’utilisateur, puis échange un code d’autorisation contre des tokens.

Étape 1 : Générer le challenge PKCE

Générez un code_verifier aléatoire et dérivez-en le code_challenge :

import { randomBytes, createHash } from 'crypto'

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

Étape 2 : Rediriger vers Authorize

Redirigez le navigateur de l’utilisateur vers l’endpoint d’autorisation :

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

Paramètre	Requis	Description
`client_id`	Oui	Votre identifiant de client OAuth
`redirect_uri`	Oui	Doit correspondre à une redirect URI enregistrée pour le client
`response_type`	Oui	Doit valoir `code` pour le flux authorization code
`code_challenge`	Oui	Hash SHA-256 du `code_verifier` encodé en base64url
`code_challenge_method`	Non	Seul `S256` est pris en charge (par défaut)
`state`	Recommandé	Valeur opaque servant à prévenir les attaques CSRF — renvoyée telle quelle dans le callback
`lang`	Non	Langue de la page de connexion (`en` ou `fr`)

L’utilisateur voit une page de connexion. Après une authentification réussie, un écran de consentement s’affiche. Après approbation, le navigateur est redirigé vers votre redirect_uri avec un code d’autorisation :

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

Les codes d’autorisation sont à usage unique et expirent après 60 secondes. Échangez-les immédiatement.

Étape 3 : Échanger le code contre des 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>"
  }'

Le code_verifier doit correspondre au code_challenge envoyé à l’étape 2 (le serveur vérifie que SHA256(code_verifier) == code_challenge). Réponse :

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

Certains clients OAuth sont configurés avec requireAuthorizationCodeFlow: true. Pour ces clients, les paramètres PKCE sont obligatoires — le flux implicite est entièrement désactivé.

Grant Password

Pour les comptes de service et les scripts d’automatisation où la connexion via le navigateur n’est pas envisageable.

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>"
  }'

Réponse :

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

Authentification à deux facteurs (OTP)

Si l’utilisateur a activé l’OTP, incluez le champ x-otp-code :

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"
  }'

Grant Refresh Token

Échangez un refresh token valide contre un nouveau token d’accès sans vous réauthentifier :

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>"
  }'

Réponse :

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

Grant Client Credentials (comptes de service)

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
    }
  }
}

Définissez REELEVANT_CLIENT_ID et REELEVANT_CLIENT_SECRET dans l’environnement de l’intégration. Conservez le secret hors du code source. Cet exemple garde le token d’accès en mémoire et en demande un nouveau 60 secondes avant son expiration. Un administrateur crée le compte de service et son secret client ; consultez le guide des comptes de service. Envoyez grant_type=client_credentials, client_id et client_secret au format JSON ou application/x-www-form-urlencoded. Vous pouvez aussi transmettre les identifiants dans un en-tête HTTP Basic :

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

Chargez ces valeurs depuis un gestionnaire de secrets ou un environnement protégé ; ne saisissez pas le secret dans les commandes ni dans l’historique du shell. Lorsqu’un en-tête HTTP Basic est présent, ses identifiants sont prioritaires sur ceux du corps. Un en-tête Basic mal formé est rejeté ; les identifiants du corps ne sont pas utilisés en remplacement.

Paramètre	Type	Requis	Défaut	Description
`grant_type`	string	Oui	—	Doit valoir `client_credentials`.
`client_id`	string	Oui, sauf s’il est fourni par HTTP Basic	—	Identifiant du compte de service.
`client_secret`	string	Oui, sauf s’il est fourni par HTTP Basic	—	Secret client, affiché une seule fois lors de sa création.

Réponse :

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

La réponse ne contient pas de refresh_token. Les tokens d’accès expirent après une heure ; demandez-en un nouveau avec les identifiants client lorsque nécessaire. Les réponses réussies incluent Cache-Control: no-store et Pragma: no-cache. Deux secrets client au maximum peuvent être actifs simultanément, ce qui permet leur rotation. La révocation d’un secret révoque aussi les tokens d’accès émis avec celui-ci. La désactivation du compte de service bloque immédiatement les nouveaux grants et invalide ses tokens d’accès existants.

Utiliser les tokens d’accès

Incluez le token d’accès dans chaque requête à l’API via l’en-tête Authorization :

Authorization: Bearer <access_token>

Cycle de vie des tokens

Type de token	Durée de vie	Renouvellement
Token d’accès	1 heure	Utilisez le grant `refresh_token` pour en obtenir un nouveau
Token d’accès client_credentials	1 heure	Demandez-en un nouveau ; aucun `refresh_token` n’est émis
Refresh token	30 jours (glissant)	Renouvelé automatiquement à chaque utilisation pour générer un nouveau token d’accès
Code d’autorisation	60 secondes	Usage unique — échangez-le immédiatement après réception

Les refresh tokens utilisent une expiration glissante : la fenêtre de 30 jours est réinitialisée à chaque utilisation du refresh token. Si vous le rafraîchissez au moins une fois par mois, le token n’expire jamais.

Révoquer des tokens

Révoquez un token d’accès ou un refresh token :

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

Révoquer un refresh token révoque également tous les tokens d’accès qui en sont dérivés. La révocation d’un secret client révoque aussi les tokens d’accès émis avec celui-ci. La désactivation de son compte de service invalide tous ses tokens d’accès.

Provisionnement SCIM

Le provisionnement entrant utilise des tokens bearer propres à une entreprise, et non des tokens OAuth utilisateur. Voir Provisionnement SCIM 2.0.

Authentification SSO

Les entreprises ayant configuré le SSO sont automatiquement redirigées vers leur fournisseur d’identité pendant le flux d’autorisation OAuth. Si le SSO est obligatoire pour l’entreprise, la connexion par mot de passe est désactivée (sauf pour les comptes de service).

Gestion des erreurs

Erreur	Statut HTTP	Cause
`invalid_client`	400	`client_id` inconnu ou inactif
`invalid_redirect_uri`	400	`redirect_uri` absente de la liste autorisée du client
`invalid_request`	400	Paramètres requis manquants (par exemple, `code_challenge` pour PKCE)
`invalid_credentials`	401	Identifiant ou mot de passe incorrect
`too_many_attempts`	429	Trop de tentatives de connexion — patientez avant de réessayer
`password_expired`	401	Le mot de passe doit être changé avant de se connecter
`otp_required`	401	Code OTP requis mais non fourni
`invalid_code`	400	Code d’autorisation invalide, expiré ou déjà utilisé
`pkce_mismatch`	400	Le `code_verifier` ne correspond pas au `code_challenge` d’origine
`InvalidClientCredentials`	401 (5512)	Identifiant ou secret invalide, révoqué ou associé à un autre type de compte
`ClientSecretLimitReached`	409 (5310)	Création d’un troisième secret client actif

Un compte de service désactivé renvoie UserDisabled.

Pages associées

Comptes de service

Créez des comptes de service et gérez leurs secrets client.

Authentification et SSO

Découvrez les options d’authentification et les modes d’intégration.

Getting Started

SDKs

Collecte de données

Web Integration

Mobile Integration

Guides

Datasources API

Contents API

Workflow API

Datasources Collector

Entity Manager API

Statistics API

Vue d’ensemble

Flux Authorization Code (PKCE)

Étape 1 : Générer le challenge PKCE

Étape 2 : Rediriger vers Authorize

Étape 3 : Échanger le code contre des tokens

Grant Password

Authentification à deux facteurs (OTP)

Grant Refresh Token

Grant Client Credentials (comptes de service)

Utiliser les tokens d’accès

Cycle de vie des tokens

Révoquer des tokens

Provisionnement SCIM

Authentification SSO

Gestion des erreurs

Pages associées

Comptes de service

Authentification et SSO

​Vue d’ensemble

​Flux Authorization Code (PKCE)

​Étape 1 : Générer le challenge PKCE

​Étape 2 : Rediriger vers Authorize

​Étape 3 : Échanger le code contre des tokens

​Grant Password

​Authentification à deux facteurs (OTP)

​Grant Refresh Token

​Grant Client Credentials (comptes de service)

​Utiliser les tokens d’accès

​Cycle de vie des tokens

​Révoquer des tokens

​Provisionnement SCIM

​Authentification SSO

​Gestion des erreurs

​Pages associées

Comptes de service

Authentification et SSO

Vue d’ensemble

Flux Authorization Code (PKCE)

Étape 1 : Générer le challenge PKCE

Étape 2 : Rediriger vers Authorize

Étape 3 : Échanger le code contre des tokens

Grant Password

Authentification à deux facteurs (OTP)

Grant Refresh Token

Grant Client Credentials (comptes de service)

Utiliser les tokens d’accès

Cycle de vie des tokens

Révoquer des tokens

Provisionnement SCIM

Authentification SSO

Gestion des erreurs

Pages associées