Skip to main content

​
Authentification

Orbit authentifie les requêtes API de deux manières : une clé d’API pour les appels de serveur à serveur, et un jeton Bearer de session pour les utilisateurs du tableau de bord. Les organisations en entreprise peuvent en outre connecter leurs utilisateurs via l’authentification unique SAML et les provisionner via SCIM. Choisissez la méthode qui correspond à la manière dont la requête est effectuée.

​
Clé d’API (serveur à serveur)

Incluez votre clé d’API dans l’en-tête X-API-Key :

​
Jeton Bearer (utilisateurs du tableau de bord)

Pour les utilisateurs du tableau de bord, utilisez des jetons Bearer JWT :
Vous pouvez également transmettre une clé d’API via Authorization: Bearer dv_live_pk_... (n’importe quelle clé dv_ — dv_live_sk_, dv_test_sk_, dv_live_pk_, dv_test_pk_) pour les environnements où l’en-tête personnalisé X-API-Key est bloqué par CORS. Le serveur accepte les deux formes : il lit d’abord X-API-Key, puis se rabat sur un jeton Bearer portant un préfixe dv_. Un JWT (qui commence par eyJ) reste traité comme un jeton de session du tableau de bord, de sorte que les deux n’entrent jamais en conflit.

​
Format des clés d’API

Une clé publique (dv_live_pk_ / dv_test_pk_) est destinée à être intégrée dans du code côté client ; elle est donc limitée à des scopes en lecture seule lors de sa création. Les scopes d’écriture et d’administration — messages:write, contacts:write, admin, le joker *, ainsi que les lectures sensibles du compte billing:read / settings:read — sont rejetés pour une clé publique avec un 422. Utilisez une clé secrète (dv_live_sk_) pour toute opération qui envoie ou modifie des données.Considérez néanmoins toute clé intégrée à un bundle navigateur ou mobile comme visible publiquement, et limitez-la aux lectures minimales dont elle a besoin.

​
Authentification unique (SAML)

Les organisations en entreprise peuvent connecter les utilisateurs du tableau de bord via un fournisseur d’identité SAML 2.0 — Okta, Microsoft Entra ID (anciennement Azure AD), OneLogin, Google Workspace ou PingFederate. Le SSO authentifie les personnes dans le tableau de bord ; il ne génère pas de clés d’API, de sorte que les appels de serveur à serveur continuent d’utiliser les méthodes ci-dessus. Un propriétaire configure la connexion sous Paramètres → Authentification unique dans le tableau de bord (ou via PATCH /api/v1/settings/saml) : définissez l’URL SSO, l’ID d’entité et le certificat de signature de votre IdP, puis utilisez Tester la connexion avant de l’activer. Chaque organisation dispose de son propre ensemble d’endpoints, identifiés par le slug de votre organisation (orgSlug). Ils se situent à la racine de l’API, et non sous /api/v1 : Pointez votre IdP vers l’endpoint des métadonnées, par exemple https://api.orbit.devotel.io/auth/saml/acme/metadata pour l’organisation acme.

​
Provisionnement d’annuaire (SCIM)

Provisionnez et déprovisionnez automatiquement les utilisateurs du tableau de bord depuis votre fournisseur d’identité via SCIM 2.0. Générez un jeton de provisionnement sous Paramètres → SCIM (ou via POST /api/v1/settings/scim/generate-token) — le jeton n’est affiché qu’une seule fois, alors copiez-le immédiatement dans votre IdP. Votre IdP envoie le jeton comme identifiant Bearer à chaque requête :
Les endpoints suivent la spécification SCIM 2.0 et renvoient application/scim+json. Ils sont identifiés par le slug de votre organisation et se situent à la racine de l’API, et non sous /api/v1 :
SAML et SCIM sont indépendants : le SSO contrôle la façon dont les utilisateurs se connectent, SCIM contrôle quels utilisateurs existent. Vous pouvez activer l’un ou l’autre séparément, même si la plupart des IdP configurent les deux ensemble.
Pour le guide complet du provisionnement — construction de l’URL de base, correspondance des rôles, vérifications de santé de l’IdP et étapes pour Okta / Entra / client générique — consultez le guide de provisionnement SCIM 2.0.