## 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](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/administration-api/) `(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](#comment-ajouter-un-autre-token) d'autres à tout moment — un par serveur ou par environnement, par exemple, afin de pouvoir en révoquer un seul sans affecter les autres. > [!CAUTION] > Ne partagez jamais le token et ne le publiez jamais dans un dépôt public. Quiconque > détient le token et l'Application ID peut envoyer des messages depuis votre compte. Si > vous soupçonnez une fuite, [régénérez](#comment-regenerer-un-token) ou > [supprimez](#comment-supprimer-un-token) le token. ## 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`. ![La partie Credentials avec la liste des tokens](docs:api-tokens/token-list_en) ## 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 ![La boîte de dialogue Afficher le jeton demandant le mot de passe](docs:api-tokens/token-show_en) > [!NOTE] > Un token affiché ne le reste que jusqu'au rechargement de la page. Après un rechargement, > il est de nouveau masqué et vous devez saisir votre mot de passe pour le revoir. ## 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 menu More actions avec Générer un nouveau, Disable et Effacer](docs:api-tokens/token-menu_en) Le portail confirme par `Token was regenerated`. > [!WARNING] > L'ancien token cesse de fonctionner immédiatement. Toutes les intégrations qui l'utilisaient > commencent à recevoir des erreurs — mettez le nouveau token en place sans attendre. ## 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. > [!CAUTION] > La suppression est définitive — le token ne peut être ni restauré, ni affiché de nouveau. Si > vous souhaitez seulement bloquer l'accès temporairement, utilisez plutôt > [la désactivation du token](#comment-desactiver-et-reactiver-un-token). 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](#comment-utiliser-le-token-dans-un-jwt-signe) 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](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-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` : ```http POST /api/1.0/simple/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json Authorization: Bearer ``` Pour que l'API l'accepte, le JWT doit se présenter ainsi : | Partie | Contenu | |:--|:--| | Header | `{"alg":"HS256","typ":"JWT"}` — l'API n'accepte aucun autre algorithme ni type | | Payload | `application_id` contenant votre [Application ID](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/administration-api/) | | Signature | HMAC-SHA256 du header et du payload, avec le token d'API comme clé | Le payload pour l'application numéro 39238 se présente donc ainsi : ```json { "application_id": 39238 } ``` > [!NOTE] > Lorsque vous envoyez un JWT, vous n'avez plus besoin de `application_id` ni de `application_token` > parmi les paramètres de la requête — l'API tire l'identité du payload. 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 : ```json { "application_id": 39238, "application_parameters": { "expire": 1800000000 } } ``` 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`.