Vue d'ensemble

CX-Engine utilise des tokens Bearer OAuth 2.0. Les tokens sont scopés à la plateforme centrale ou à un workspace spécifique. Utilisez POST /api/switch-to pour changer de scope sans vous reconnecter.

OAuth 2.0

CX-Engine prend en charge deux types d'attribution OAuth 2.0 pour l'accès délégué et les communications machine-à-machine :

Type d'attribution Cas d'usage
Authorization Code Accès délégué interactif via redirection navigateur
Client Credentials Accès serveur-à-serveur sans interaction utilisateur

Prérequis : Pour utiliser un flux OAuth 2.0, vous devez d'abord créer un client OAuth dans votre tableau de bord CX-Engine. Cela vous fournit un client_id et un client_secret requis pour tous les types d'attribution.

Authorization Code Grant

Utilisé lorsque votre application agit pour le compte d'un utilisateur. L'utilisateur approuve l'accès dans son navigateur et votre application reçoit un code d'autorisation à échanger contre des tokens.

Étape 1 — Rediriger l'utilisateur

GET /oauth/authorize

Paramètre Type Description
client_id string L'identifiant client de votre application
redirect_uri string URI de redirection après autorisation
response_type string Doit être code
scope string Liste de scopes séparés par des espaces (optionnel)
state string Chaîne aléatoire pour la protection CSRF (recommandé)

Le redirect_uri doit correspondre exactement à l'une des URIs de redirection enregistrées sur votre client OAuth. Les requêtes avec une URI non enregistrée seront rejetées.

L'utilisateur voit un écran d'approbation. En cas d'approbation, il est redirigé vers votre redirect_uri avec un paramètre code.

Étape 2 — Échanger le code contre des tokens

POST /oauth/token

Champ Type Description
grant_type string authorization_code
client_id string Votre identifiant client
client_secret string Votre secret client
redirect_uri string Doit correspondre à l'URI utilisée à l'étape 1
code string Le code d'autorisation reçu

Réponse 200

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1Q...",
  "refresh_token": "def50200..."
}

Client Credentials Grant

Utilisé pour les communications serveur-à-serveur sans interaction utilisateur.

POST /oauth/token

Champ Type Description
grant_type string client_credentials
client_id string Votre identifiant client
client_secret string Votre secret client
scope string Liste de scopes séparés par des espaces (optionnel)

Réponse 200

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1Q..."
}

Les tokens client credentials ne comprennent pas de refresh token.

Rafraîchir un token

POST /oauth/token

Champ Type Description
grant_type string refresh_token
refresh_token string Le refresh token d'une réponse précédente
client_id string Votre identifiant client
client_secret string Votre secret client
scope string Doit être identique ou un sous-ensemble des scopes d'origine

Réponse 200

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1Q...",
  "refresh_token": "def50200..."
}

Rotation du refresh token : Chaque appel à cet endpoint invalide le refresh token précédent et en émet un nouveau. Vous devez persister le refresh_token retourné à chaque réponse — réutiliser un ancien refresh token entraînera une erreur.

Révoquer un token

DELETE /oauth/tokens/{token_id}

En-têtes : Authorization: Bearer {access_token}

Réponse 204 — token révoqué.

API centrale

POST /api/login

Authentifie un utilisateur sur la plateforme centrale et retourne un token Bearer scopé central.

Corps de la requête

Champ Type Requis Description
email string oui Adresse email de l'utilisateur
password string oui Mot de passe

Réponse 200

{
  "message": "success",
  "token": "eyJ0eXAiOiJKV1Q...",
  "user": { "id": 1, "name": "Jane Doe", "email": "jane@exemple.com" },
  "workspaces": [...],
  "pending_invites": [...]
}

Réponse 401

{ "response": "invalid username and/or password." }

POST /api/register

Crée un nouveau compte utilisateur et retourne un token Bearer scopé central.

Corps de la requête

Champ Type Requis Description
name string oui Nom complet
email string oui Adresse email
password string oui Mot de passe
phone string non Numéro de téléphone
mobile_phone string non Numéro de mobile

Réponse 200

{
  "message": "success",
  "token": "eyJ0eXAiOiJKV1Q...",
  "user": { ... },
  "workspaces": [],
  "pending_invites": []
}

Réponse 422 — email déjà utilisé

{ "message": "An user with this e-mail address already exists." }

POST /api/logout

Révoque tous les tokens de l'utilisateur authentifié sur la plateforme centrale et tous les workspaces.

En-têtes : Authorization: Bearer {token-central}

Réponse 200

{ "message": "success" }

GET /api/whoami

Retourne l'identité de l'utilisateur actuellement authentifié ainsi que ses workspaces.

En-têtes : Authorization: Bearer {token-central}

Réponse 200

{
  "message": "success",
  "user": { "id": 1, "name": "Jane Doe", "email": "jane@exemple.com" },
  "workspaces": [...],
  "current_workspace": null
}

Lorsque l'appel est effectué avec un token workspace, current_workspace inclut le nom du workspace, le groupe, les rôles et les permissions :

{
  "current_workspace": {
    "name": "Acme Corp",
    "group": "admin",
    "roles": ["manager"],
    "permissions": ["customer.view", "customer.create"]
  }
}

POST /api/switch-to

Émet un nouveau token scopé vers un workspace différent, ou de retour vers le central, sans nécessiter de reconnexion.

En-têtes : Authorization: Bearer {token-actuel}

Corps — basculer vers un workspace

Champ Type Requis Description
workspace_id string oui* ID du workspace cible

Corps — revenir au central

Champ Type Requis Description
central boolean oui* Passer true pour revenir au scope central

*L'un de workspace_id ou central est requis.

Réponse 200

{
  "message": "success",
  "user": { ... },
  "workspace": {
    "id": "acme",
    "name": "Acme Corp",
    "group": "admin",
    "roles": ["manager"],
    "permissions": ["customer.view", ...]
  },
  "domains": ["acme.cx-engine.app"],
  "token": "eyJ0eXAiOiJKV1Q..."
}

Réponse 403 — workspace inaccessible

{ "message": "You do not have access to this workspace." }

API workspace

POST /api/login (workspace)

Authentifie un utilisateur sur un workspace spécifique et retourne un token Bearer scopé workspace. Envoyez cette requête vers le sous-domaine du workspace.

Corps de la requête

Champ Type Requis
email string oui
password string oui

Réponse 200

{
  "message": "success",
  "token": "eyJ0eXAiOiJKV1Q...",
  "user": { ... }
}

POST /api/logout (workspace)

Révoque uniquement le token workspace actuel.

En-têtes : Authorization: Bearer {token-workspace}

Réponse 200

{ "message": "success" }
Introduction CRM Lookup