Skip to Content

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 :

  1. Choisissez Ajouter une application dans la section déléguée par l'utilisateur ou dans la section client (machine-to-machine).
  2. Sélectionnez l'application.
  3. Sélectionnez les scopes à accorder, ou choisissez grant all permissions pour inclure automatiquement les scopes actuels et futurs.
  4. 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.

La liste des API dans l'Admin Console

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 :

  1. Sélectionnez l'une des applications machine-to-machine autorisées.
  2. 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.
  3. 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.
  4. 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_token ne 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.read

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

  1. Créez une application machine-to-machine, voir Applications.
  2. 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.
  3. 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.
  4. Appelez les endpoints de gestion sous /api/v1/... avec le jeton obtenu dans l'en-tête Authorization: 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é.

PlanRequêtes de jetons par minute
Trial30
Free60
Essential1 200
Advanced6 000
Pro30 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.

PlanJetons par mois
Trial / Free1 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

TermeSignification
Identifiant (audience)La valeur qui identifie l'API ; figure dans les jetons émis pour elle.
Scope / autorisationUne capacité unique qu'un jeton peut porter.
User policyIndique si des applications interactives peuvent obtenir des jetons au nom d'un utilisateur.
Client policyIndique si des applications peuvent obtenir des jetons pour elles-mêmes (machine-to-machine).
GrantL'autorisation explicite d'une application à appeler cette API avec des scopes précis.
RBACL'intégration des rôles et autorisations d'un utilisateur dans les jetons de l'API.
Token exchangeL'é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.

Sur cette page