> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentifier les requêtes de l'API Orbit avec des clés et des jetons

> Authentifiez les requêtes de l'API Orbit à l'aide de clés d'API pour les appels de serveur à serveur ou de jetons de session Bearer, avec en plus le SSO SAML pour les utilisateurs du tableau de bord en entreprise.

# 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](#single-sign-on-saml)
et les provisionner via [SCIM](#directory-provisioning-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` :

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

## Jeton Bearer (utilisateurs du tableau de bord)

Pour les utilisateurs du tableau de bord, utilisez des jetons Bearer JWT :

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "Authorization: Bearer eyJhbG..."
```

<Note>
  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.
</Note>

## Format des clés d'API

| Type                   | Préfixe       | Utilisation                         |
| ---------------------- | ------------- | ----------------------------------- |
| Secrète de production  | `dv_live_sk_` | Appels API côté serveur             |
| Secrète de test        | `dv_test_sk_` | Appels API côté serveur (mode test) |
| Publique de production | `dv_live_pk_` | Côté client (SDK navigateur)        |
| Publique de test       | `dv_test_pk_` | Côté client (mode test)             |

<Warning>
  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.
</Warning>

## 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` :

| Méthode | Endpoint                        | Objectif                                                                |
| ------- | ------------------------------- | ----------------------------------------------------------------------- |
| GET     | `/auth/saml/{orgSlug}/metadata` | Métadonnées XML du fournisseur de services à importer dans votre IdP    |
| GET     | `/auth/saml/{orgSlug}/login`    | Démarrer le flux SSO (redirige vers votre IdP)                          |
| POST    | `/auth/saml/{orgSlug}/callback` | Assertion Consumer Service (ACS) — votre IdP y envoie la réponse signée |
| GET     | `/auth/saml/{orgSlug}/logout`   | Démarrer la déconnexion unique                                          |

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 :

```bash theme={null}
curl https://api.orbit.devotel.io/scim/v2/acme/Users \
  -H "Authorization: Bearer <your-scim-token>"
```

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` :

| Ressource  | Endpoints                                                                                                             |
| ---------- | --------------------------------------------------------------------------------------------------------------------- |
| Users      | `/scim/v2/{orgSlug}/Users` (lister, créer), `/scim/v2/{orgSlug}/Users/{id}` (obtenir, remplacer, modifier, supprimer) |
| Groups     | `/scim/v2/{orgSlug}/Groups` (lister, créer/mettre à jour), `/scim/v2/{orgSlug}/Groups/{id}` (obtenir)                 |
| Découverte | `/scim/v2/{orgSlug}/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`                                              |

<Note>
  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.
</Note>

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](/compliance/scim-provisioning).