Tokens d'API

Qu'est-ce qu'un token d'API

Un token d'API (APPLICATION_TOKEN) est la clé secrète avec laquelle votre application s'authentifie auprès de l'API BulkGate. Avec l'Application ID (APPLICATION_ID), il forme l'ensemble complet des identifiants d'accès — sans les deux, l'API rejette la requête.

Le token est une chaîne aléatoire de 50 caractères composée de chiffres et de lettres minuscules et majuscules. Il est stocké sous forme chiffrée et n'expire pas — il reste valable jusqu'à ce que vous le régénériez, le désactiviez ou le supprimiez vous-même.

Un token est créé automatiquement au moment où vous créez l'API. Vous pouvez en ajouter d'autres à tout moment — un par serveur ou par environnement, par exemple, afin de pouvoir en révoquer un seul sans affecter les autres.

Où trouver le token

1. Cliquez sur Modules et API dans le menu du portail
2. Cliquez sur la carte de votre application sous Mes API et modules
3. Restez sur l'onglet Réglages et trouvez la section Identifiants de connexion

Elle contient l'Application ID et, en dessous, sous le sous-titre Application Token, la liste des tokens de cette application. Un token n'est jamais affiché directement — vous n'en voyez que les quatre premiers et les quatre derniers caractères, le reste est remplacé par des astérisques.

L'icône à gauche indique l'état du token : verte signifie activé, rouge signifie désactivé. Un token désactivé est en outre barré.

Le bouton en forme d'œil barré à droite de chaque token l'affiche ; les autres actions sont cachées derrière l'icône à trois points Plus d'actions.

Comment afficher et copier un token

1. Cliquez sur l'icône d'œil barré à côté du token que vous souhaitez voir
2. La boîte de dialogue Afficher le jeton s'ouvre et vous invite à vérifier votre environnement
3. Saisissez le mot de passe de votre compte et cliquez sur Continuer
4. Le token s'affiche en entier et l'icône devient Copier, qui le copie dans le presse-papiers

Comment ajouter un autre token

1. Cliquez sur Ajouter jeton en bas de la section Identifiants de connexion
2. Saisissez le mot de passe de votre compte
3. Cliquez sur Ajouter

Le portail confirme par Token was created et affiche le nouveau token en entier — copiez-le tout de suite, car après un rechargement il est masqué comme les autres. Le nombre de tokens par application n'est pas limité.

Comment régénérer un token

La régénération remplace le token existant par un nouveau. Il garde sa place dans la liste, seule sa valeur change.

1. Cliquez sur Plus d'actions à côté du token et choisissez Générer un nouveau
2. Saisissez le mot de passe de votre compte
3. Cliquez sur Générer un nouveau

Le portail confirme par Token was regenerated.

Comment désactiver et réactiver un token

La désactivation est l'alternative réversible à la suppression : le token reste dans la liste, mais il ne peut plus servir à l'authentification.

1. Cliquez sur Plus d'actions à côté du token
2. Choisissez Désactiver, ou Activer pour un token déjà désactivé
3. Confirmez dans la boîte de dialogue qui s'ouvre

Le portail confirme par Le jeton a été désactivé ou Le jeton a été activé. Aucun mot de passe n'est demandé pour cette action.

Comment supprimer un token

1. Cliquez sur Plus d'actions à côté du token et choisissez Effacer
2. Confirmez par Effacer dans la boîte de dialogue Effacer jeton

Le portail confirme par Jeton a été supprimé. Aucun mot de passe n'est demandé pour cette action non plus.

Tous les tokens d'une application disparaissent également dès que vous supprimez l'application elle-même.

Comment le token est envoyé à l'API

Vous transmettez l'Application ID et le token dans les paramètres application_id et application_token — soit dans le corps de la requête, soit dans la query string. L'autre possibilité consiste à signer un JWT avec le token et à l'envoyer dans un en-tête.

Un token invalide, désactivé ou supprimé entraîne une réponse avec le code HTTP 401 et le type d'erreur unknown_identity. Vous obtenez la même réponse lorsque l'application elle-même est désactivée, ou lorsqu'elle a des adresses IP autorisées configurées et que la requête provient d'ailleurs. Les autres erreurs sont répertoriées sur la page Types d'erreurs de l'API.

Comment utiliser le token dans un JWT signé

Au lieu d'envoyer le token avec chaque requête, vous pouvez signer un JWT avec celui-ci et envoyer ce dernier à la place. Le token reste alors chez vous — seule la signature qui en est dérivée transite par le réseau.

Placez le JWT finalisé dans l'en-tête Authorization :

Pour que l'API l'accepte, le JWT doit se présenter ainsi :

Le payload pour l'application numéro 39238 se présente donc ainsi :

Vous pouvez limiter la durée de vie d'un JWT donné avec le champ expire à l'intérieur de application_parameters. La valeur est un timestamp Unix en secondes ; une fois celui-ci atteint, le JWT cesse de fonctionner :

Sans ce champ, le JWT est valable aussi longtemps que le token qui l'a signé. Le champ est donc utile partout où vous transmettez le JWT à un tiers — vous le signez avec une courte durée de vie et le token lui-même reste chez vous.

La signature est vérifiée par rapport à chaque token activé de l'application, vous pouvez donc signer le JWT avec n'importe lequel d'entre eux. Un token désactivé ou supprimé ne passe pas — il en va de même que ci-dessus : une réponse avec le code HTTP 401 et le type d'erreur unknown_identity.