APIs
Protégez vos APIs en tant que ressources OAuth : définissez des scopes, contrôlez l'accès machine-to-machine et utilisateur, réglez format et durée des jetons.
Une API représente une ressource protégée pour laquelle les applications obtiennent des jetons d'accès. Enregistrer une API indique à la plateforme l'identifiant de la ressource (son audience), les scopes (autorisations) qu'elle expose, les applications autorisées à l'appeler, ainsi que la forme et la signature des jetons d'accès émis pour elle.
Vous gérez les APIs sous Intégrations → API dans l'Admin Console.
Ce qu'est une API
Chaque API possède :
- un nom : un libellé destiné aux administrateurs, et
- un identifiant : la valeur d'audience qui figure dans les jetons émis pour cette API (par exemple
https://api.example.com).
Sur une API personnalisée, vous pouvez aussi désigner des contacts, les employés à qui s'adresser à son sujet. Ils sont purement informatifs et ne reçoivent aucun droit.
Il en existe deux types :
- System API : l'API de gestion propre à la plateforme. Son nom, son identifiant et ses scopes sont fixes et ne peuvent pas être modifiés.
- Custom API : une API que vous enregistrez et gouvernez : vous définissez ses scopes, qui peut l'appeler et ses paramètres de jetons.
Scopes (autorisations)
Un scope est une autorisation unique qu'un jeton peut porter, par exemple read:documents ou orders.write.
- La System API expose un catalogue fixe de scopes de gestion (par exemple
users.read,users.write,groups.read,roles.write,logs.read). Ce sont les scopes que vous accordez aux applications qui appellent l'API de gestion propre à la plateforme. - Une Custom API expose les scopes que vous définissez. Dans l'onglet des autorisations de l'API, ajoutez chaque scope avec un nom et une description. Quelques scopes OpenID Connect réservés (comme
openid,profile,email,offline_access) ne peuvent pas être redéfinis.
Certains scopes de gestion se placent délibérément à côté de leur scope de base au lieu d'être inclus par celui-ci. Celui à connaître est users.mfa.read, qui couvre les enregistrements MFA d'un utilisateur (quels seconds facteurs sont enregistrés et quand chacun a été utilisé pour la dernière fois). Il est requis sur chaque endpoint qui renvoie un utilisateur, y compris dans les réponses des appels de création, de mise à jour, de suppression, de désactivation et d'activation. Un jeton qui ne porte que users.read ou users.write reçoit l'utilisateur sans la liste des enregistrements ; accordez donc users.mfa.read en plus lorsqu'une intégration en a besoin.
Qui peut appeler une API
Deux politiques indépendantes contrôlent l'accès, une pour chaque type d'appelant :
Accès délégué par l'utilisateur
Lorsqu'une application interactive demande un jeton au nom d'un utilisateur connecté, la user policy de l'API décide si c'est autorisé :
- Allow all : toute application interactive peut demander des jetons pour cette API.
- Require grant : seules les applications que vous avez explicitement autorisées peuvent demander des jetons, et uniquement pour les scopes que vous leur accordez.
- Deny all : aucune application interactive ne peut demander de jetons.
Accès machine-to-machine
Lorsqu'une application s'authentifie en son propre nom avec le grant client-credentials (sans utilisateur), la client policy de l'API décide si c'est autorisé :
- Require grant : seules les applications que vous avez explicitement autorisées peuvent demander des jetons, limités aux scopes accordés.
- Deny all : aucune application machine-to-machine ne peut demander de jetons.
Autoriser une application
Lorsqu'une politique est définie sur require grant, autorisez une application depuis l'onglet Accès à l'application de l'API :
- Choisissez Ajouter une application dans la section déléguée par l'utilisateur ou dans la section client (machine-to-machine).
- Sélectionnez l'application.
- Sélectionnez les scopes à accorder, ou choisissez grant all permissions pour inclure automatiquement les scopes actuels et futurs.
- Enregistrez. Les jetons que la plateforme émet pour cette application et cette API portent désormais les scopes accordés.
Une application machine-to-machine est généralement du type d'application machine-to-machine, voir Applications.

Tester un jeton d'API
Dès qu'au moins une application machine-to-machine est autorisée pour une API (avec le grant client-credentials), l'onglet Test de l'API vous permet d'essayer un jeton de bout en bout sans écrire de code :
- Sélectionnez l'une des applications machine-to-machine autorisées.
- La page affiche un exemple de requête de jeton prêt à l'emploi vers le token endpoint, avec l'ID client et le secret de cette application et l'identifiant de cette API comme audience.
- Elle affiche la réponse de jeton et décode le jeton d'accès émis en header, payload et signature, afin que vous puissiez vérifier que l'audience et les scopes accordés sont ceux attendus.
- Elle affiche un exemple d'appel d'API qui envoie le jeton dans un en-tête
Bearer.
Copiez les commandes pour les exécuter dans votre propre terminal. Si l'onglet Test vous demande d'abord d'autoriser une application, accordez l'accès à une application machine-to-machine dans l'onglet Accès à l'application et rechargez la page.
Resource indicators et jetons
Chaque jeton d'accès que la plateforme émet pour une API porte l'identifiant de cette API comme audience, afin que la ressource puisse vérifier que le jeton lui était destiné. Les applications choisissent l'API pour laquelle elles veulent un jeton au moyen du resource indicator, ce qui permet à une même application de détenir des jetons distincts, limités par audience, pour plusieurs APIs.
Dans l'onglet des paramètres de l'API, vous contrôlez la forme de ces jetons :
- Algorithme de signature : l'algorithme asymétrique (RS256, RS384, RS512 ou PS256) utilisé pour signer les jetons. Choisissez PS256 pour une API appelée par une application qui utilise un profil de sécurité Financial-grade API : ce profil signe les jetons propres à l'application avec PS256 et déconseille RS256. Ce paramètre est indépendant du profil et doit donc être modifié ici aussi.
- Access token lifetime : la durée de validité d'un jeton (un jour par défaut).
- Implicit access token lifetime : une durée plus courte appliquée aux jetons émis via les flux implicites basés sur le navigateur (deux heures par défaut).
Une API ou plusieurs ?
Un jeton d'accès porte toujours exactement une audience. Aucun jeton multi-audience n'est émis : un jeton créé pour une API n'est pas accepté par une autre (voir L'API comme contrat vérifiable). Si votre backend est un ensemble de microservices, cela laisse une décision de conception à prendre :
Une API logique pour un domaine de confiance. Enregistrez une seule API dont l'identifiant représente l'ensemble du backend (par exemple https://api.example.com) et donnez à chaque service son propre espace de noms de scopes (orders.read, inventory.write, etc.). Chaque service valide la même audience et n'applique que ses propres scopes ; le client détient un seul jeton pour tout le backend, et un nouveau service s'ajoute par de nouveaux scopes plutôt que par un nouvel enregistrement. Choisissez cette option lorsque les services sont développés et exploités ensemble, typiquement derrière une seule passerelle. Tenez compte du compromis : au sein de l'audience partagée, les services ne s'isolent plus les uns des autres par le contrôle d'audience (chacun accepte un jeton envoyé à un service voisin), mais uniquement par les scopes.
Une API par frontière de confiance. Enregistrez des APIs distinctes lorsque les ressources ont des niveaux de confiance ou des propriétaires différents, ou lorsque des tiers sont impliqués. Un client demande alors un jeton distinct par API via le resource indicator (voir Resource indicators et jetons), et un service backend peut échanger un jeton qu'il détient déjà via le token exchange. De part et d'autre de la frontière, le contrôle d'audience garde tout son sens : un jeton intercepté sur une API est sans valeur sur l'autre.
Combiner les deux est courant : une API logique pour le cœur cohérent, des APIs distinctes pour les parties qui exigent une isolation plus forte.
Jusqu'où transmettre le jeton d'un utilisateur. Traitez le jeton d'accès de l'utilisateur comme un identifiant, pas comme un contexte de requête. Transmettez-le au plus sur un saut, du client à la périphérie de votre API (la passerelle ou le premier service). Les services situés plus loin dans une chaîne d'appels doivent soit se trouver derrière l'audience partagée de l'API logique, soit recevoir un jeton plus restreint créé via le token exchange ; chaque saut supplémentaire parcouru par le jeton d'origine élargit les endroits où un jeton divulgué peut être rejoué.
Token exchange
Le token endpoint prend en charge OAuth 2.0 Token Exchange (RFC 8693), afin qu'un service puisse appeler une API en aval au nom d'un utilisateur connecté sans transmettre le jeton d'origine : l'application échange un jeton d'accès utilisateur qu'elle détient déjà contre un nouveau jeton, plus restreint, ciblant une autre API.
Le grant est délibérément limité à la réduction de portée :
- Seule une application web (confidentielle) peut l'utiliser, et uniquement lorsque Échange de jetons est activé parmi ses types de grant (voir Applications).
- Le subject token doit être un jeton d'accès utilisateur encore valide émis pour la même application que celle qui effectue l'échange. L'échange de jetons d'une autre application, de jetons sans utilisateur, ou la délégation avec un
actor_tokenne sont pas pris en charge. - La requête désigne exactement une API cible via
resource. La politique d'accès délégué par l'utilisateur de l'API cible s'applique à l'application qui effectue l'échange, comme pour toute autre requête de jeton. - Le jeton émis n'est jamais plus large que le subject token : ses scopes sont l'intersection des scopes demandés, des scopes du subject token, des scopes de l'API cible et de ce à quoi l'utilisateur a droit.
- Le nouveau jeton reste lié au même utilisateur et à la même session et suit les paramètres de durée de vie des jetons de l'API cible.
Exemple de requête vers le token endpoint (l'application s'authentifie comme d'habitude, par exemple avec son secret client) :
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<the user access token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&resource=https://inventory.example.com
&scope=inventory.readLa réponse contient le nouveau access_token avec expires_in et le scope effectivement accordé.
Scopes et autorisations
Définir un scope sur une API le rend seulement demandable : cela n'en accorde l'accès à personne. Ce qui figure réellement dans un jeton est décidé séparément :
- Pour les jetons machine-to-machine, le jeton porte exactement les scopes autorisés par le grant client de l'application (voir Autoriser une application). Un client machine n'a ni utilisateur ni rôles ; attribuer un rôle à une application machine-to-machine n'a donc aucun effet, ses scopes proviennent uniquement du grant.
- Pour les jetons porteurs d'un utilisateur (émis lorsqu'une application interactive demande un jeton au nom d'un utilisateur connecté), le contrôle d'accès basé sur les rôles décide des scopes auxquels l'utilisateur a droit. Les scopes qui se retrouvent dans le jeton sont l'intersection de ce que l'application a demandé et de ce à quoi l'utilisateur a droit.
C'est la réponse habituelle à la question « pourquoi le scope que j'ai demandé manque-t-il silencieusement dans mon jeton ? » : le scope a été demandé, mais l'appelant n'y avait pas droit, il a donc été ignoré plutôt que refusé.
Défense en profondeur : un scope présent dans un jeton est une autorisation accordée, pas une garantie. Votre API doit toujours appliquer ses propres contrôles au niveau des objets (cet utilisateur possède-t-il cet enregistrement ?) ; un jeton valide avec un scope large ne remplace pas l'autorisation sur la ressource elle-même.
Contrôle d'accès basé sur les rôles
Remarque sur le plan : le contrôle d'accès basé sur les rôles est disponible à partir du plan Advanced (et dans la version d'essai).
Une API personnalisée peut activer le RBAC, ce qui permet à la plateforme d'intégrer directement les rôles et autorisations d'un utilisateur dans les jetons qu'elle émet pour cette API. Dans l'onglet des paramètres de l'API :
- Inclure les rôles et les autorisations (RBAC) l'active pour l'API.
- Inclure le claim permissions ajoute les scopes accordés à l'utilisateur pour cette API dans un claim
permissions. - Inclure le claim roles ajoute les noms des rôles de l'utilisateur dans un claim
roles.
Ces claims ne sont ajoutés qu'aux jetons porteurs d'un utilisateur. L'application prend ensuite ses décisions d'autorisation à partir de ces claims. Pour définir des rôles et les attribuer à des utilisateurs et des groupes, voir Rôles.
C'est sur le jeton d'accès que ces décisions doivent reposer. Un claim roles parvient aussi dans l'ID token lorsqu'une application demande le scope roles, mais celui-ci ne sert qu'à l'affichage, voir Appliquer sur le jeton d'accès, pas sur l'ID token.
L'API comme contrat vérifiable
Une API enregistrée est, en pratique, un contrat entre vous et le serveur de ressources :
- Son identifiant est stable et devient l'audience de chaque jeton émis pour elle.
- La plateforme signe chaque jeton avec sa clé de signature (voir Clés de signature).
- Le serveur de ressources valide le jeton avant de faire confiance à un quelconque scope : il vérifie la signature, que l'émetteur est bien cette plateforme et que l'audience correspond à son propre identifiant, puis il lit les scopes.
Si l'une de ces vérifications échoue, le serveur de ressources doit rejeter la requête d'emblée.
Appeler l'API de gestion (démarrage rapide machine-to-machine)
Pour permettre à un script ou à un service backend d'appeler l'API de gestion propre à la plateforme :
- Créez une application machine-to-machine, voir Applications.
- Dans l'onglet d'accès aux applications de la System API, accordez à cette application les scopes de gestion dont elle a besoin (par exemple
users.read,groups.write). N'accordez que les scopes que l'intégration utilise réellement. - Depuis votre service, demandez un jeton avec le grant client-credentials auprès du token endpoint, en utilisant l'identifiant de la System API comme audience.
- Appelez les endpoints de gestion sous
/api/v1/...avec le jeton obtenu dans l'en-têteAuthorization: Bearer.
L'onglet Test de la System API génère exactement ces deux commandes pour vous, préremplies avec une vraie application ; copiez-les comme point de départ.
Un jeton cesse de fonctionner avant son expiration dès que l'application perd son accès à la System API, que son client secret fait l'objet d'une rotation ou que l'application est supprimée. Le service reçoit alors HTTP 401 et doit demander un nouveau jeton.
Limites des jetons machine-to-machine
Deux limites s'appliquent aux jetons émis via le grant client-credentials. Toutes deux sont affichées sur la vue d'ensemble Intégrations → API. Les jetons des connexions utilisateur interactives ne sont jamais concernés par l'une ou l'autre.
Requêtes de jetons par minute et par client : la limite de débit. Les requêtes qui la dépassent reçoivent une réponse HTTP 429 avec un en-tête Retry-After ; le client peut réessayer une fois le délai indiqué dans l'en-tête écoulé.
| Plan | Requêtes de jetons par minute |
|---|---|
| Trial | 30 |
| Free | 60 |
| Essential | 1 200 |
| Advanced | 6 000 |
| Pro | 30 000 |
Jetons par mois, pour tout le tenant : un budget de volume qui n'existe que sur les plans d'entrée de gamme. Il couvre toutes les applications machine-to-machine et toutes les APIs ensemble et est réinitialisé le 1er de chaque mois. Une fois épuisé, les requêtes client-credentials suivantes reçoivent la réponse access_denied jusqu'au début du mois suivant.
| Plan | Jetons par mois |
|---|---|
| Trial / Free | 1 000 |
| Essential et au-delà | Illimité |
Un client qui met son jeton d'accès en cache pendant toute sa durée de vie a besoin d'environ 720 jetons par mois et reste très en deçà des deux limites ; l'une ou l'autre n'est donc normalement atteinte que par un client qui demande un nouveau jeton pour chaque appel d'API. Mettez le jeton en cache dans le service appelant et réutilisez-le jusque peu avant son expiration ; la durée de vie du jeton se configure par API dans l'onglet des paramètres de l'API.
Référence développeur / API
La plateforme fournit une documentation d'API interactive intégrée au produit sous /admin/api-docs. Elle liste chaque endpoint de gestion avec ses paramètres et vous permet d'essayer les appels dans le navigateur ; vous pouvez aussi télécharger la définition OpenAPI lisible par machine depuis la même page.
L'API de gestion couvre l'administration des utilisateurs, groupes, organisations, applications, rôles, journaux et appareils. Utilisez /admin/api-docs comme référence faisant autorité pour les endpoints, plutôt qu'une liste statique ici.
Référence
| Terme | Signification |
|---|---|
| Identifiant (audience) | La valeur qui identifie l'API ; figure dans les jetons émis pour elle. |
| Scope / autorisation | Une capacité unique qu'un jeton peut porter. |
| User policy | Indique si des applications interactives peuvent obtenir des jetons au nom d'un utilisateur. |
| Client policy | Indique si des applications peuvent obtenir des jetons pour elles-mêmes (machine-to-machine). |
| Grant | L'autorisation explicite d'une application à appeler cette API avec des scopes précis. |
| RBAC | L'intégration des rôles et autorisations d'un utilisateur dans les jetons de l'API. |
| Token exchange | L'échange d'un jeton d'accès utilisateur contre un jeton plus restreint ciblant une autre API (RFC 8693). |
Dépannage
- La requête de jeton est rejetée avec un scope invalide. Une application ne peut demander que les scopes qui lui ont été accordés sur l'API. Ajoutez le scope au grant de l'application pour cette API, puis demandez un nouveau jeton.
- Les appels renvoient une erreur de scope insuffisant alors qu'un jeton a été émis. Une requête n'aboutit que si le jeton porte réellement le scope exigé par l'endpoint. Décodez le jeton et vérifiez que les scopes accordés l'incluent ; les scopes non accordés à l'application sont silencieusement retirés du jeton.
- Le jeton a la mauvaise audience. Le jeton doit être demandé pour l'identifiant (audience) de cette API. Un jeton créé pour une autre API, ou sans audience, n'est pas accepté ici.
- Le test de jeton ne renvoie rien ou une erreur. Le test émet un jeton pour l'application et les scopes sélectionnés. Vérifiez que l'application dispose d'un grant actif sur cette API et qu'au moins un scope est sélectionné.
- Un token exchange est rejeté. Le subject token doit être un jeton d'accès encore valide, porteur d'un utilisateur et émis pour la même application que celle qui effectue l'échange ; l'application doit avoir le grant token-exchange activé, et la requête doit désigner exactement une API cible via
resource. Les jetons machine-to-machine (sans utilisateur) ne peuvent pas être échangés.
Voir aussi le glossaire.
Provisionnement d'applications
Créez, mettez à jour et désactivez automatiquement des comptes dans les applications en aval via SCIM sortant, avec mappages d'attributs et de groupes.
Rôles
Regroupez des permissions d'API dans des rôles et attribuez-les à des utilisateurs et groupes pour une autorisation par rôle dans les applications.