Jetons d'API

Un jeton d'API est une clé qu'on révoque. Ce n'est pas le solde de « tokens » du compte, qui est une monnaie (1 token = 1 page scannée lors d'un scan complet de site). Les deux vivent sur le même écran, parce que c'est là qu'on vient quand on cherche « ce qui se compte », mais ils ne se ressemblent pas : l'un s'achète, l'autre se frappe et se révoque. Cette page parle des jetons.

Ce que PostShip fait

Un jeton commence par psk_ suivi de 32 caractères tirés d'un générateur cryptographique (24 octets, en base64url). Le secret n'existe qu'une fois, au moment de la frappe, et n'est jamais stocké : la base ne garde que son empreinte SHA-256 et un préfixe lisible — psk_ et six caractères — pour le reconnaître dans une liste sans pouvoir s'en servir. Une clé perdue se révoque et se refrappe ; elle ne se retrouve pas, et c'est la seule promesse qu'on peut tenir honnêtement.

Pourquoi SHA-256 nu plutôt qu'un bcrypt : un jeton de 32 octets tirés au hasard n'a pas de dictionnaire à lui opposer, et le ralentissement qu'une fonction de dérivation apporterait se paierait à chaque appel de CI. La comparaison se fait en temps constant — pas parce qu'un attaquant pourrait deviner 192 bits à la milliseconde, mais parce que la règle « on ne compare pas un secret avec === » n'a pas d'exception qui vaille la discussion suivante.

À chaque appel, PostShip note la date de dernière utilisation du jeton. C'est ce qui permet d'en révoquer un sans se demander s'il tourne encore quelque part.

Un jeton porte les droits de son propriétaire, ni plus ni moins : les projets du compte et ceux partagés en tant que membre accepté, en lecture, plus la vérification à la demande. Il sert à toutes les routes de l'API et au serveur MCP.

Régler

Paramètres → API & tokens → carte Jetons d'API.

1. Créer un jeton : donnez-lui un nom (60 caractères, par exemple « CI du site », « Poste de Léa ») et validez. Le nom est ce que vous lirez le jour où il faudra choisir lequel révoquer.
2. Le jeton s'affiche dans la page, avec un bouton de copie, et y reste jusqu'à ce que vous refermiez le bloc : « Jeton créé — copiez-le maintenant, il ne sera plus affiché. » Un secret montré une seule fois doit rester à l'écran jusqu'à ce qu'on s'en aille, pas disparaître dans une notification de cinq secondes.
3. Collez-le là où il servira : un secret de CI, une variable d'environnement, le fichier de configuration MCP. Jamais en argument d'une commande — voir Vérifier depuis votre CI.
4. Révoquer : chaque jeton de la liste a son bouton. Immédiat et définitif : le prochain appel répond 401.

La liste montre pour chaque jeton son nom, son préfixe (psk_a1b2c3…), et « utilisé il y a 2 h » ou « jamais utilisé ».

Cinq jetons actifs au maximum

De quoi avoir une CI, un poste et deux machines, sans qu'un compte compromis devienne un trousseau. Au sixième : « 5 jetons actifs au maximum — révoquez-en un d'abord. » Un jeton révoqué ne compte plus.

Ce qui déclenche une alerte

Rien : un jeton n'envoie pas d'alerte, et sa création ou sa révocation ne sont pas notifiées. Un jeton révoqué ou inconnu répond 401 avec « Jeton d'API invalide ou révoqué. » sur toutes les routes, et « Jeton d'API PostShip invalide ou révoqué » sur le serveur MCP.

Limites et plans

Le quota mensuel est par compte, pas par jeton : cinq jetons ne font pas cinq fois le quota. Voir les plans.

Dépannage

J'ai fermé la page avant de copier le jeton. Comment le retrouver ?

Impossible : il n'est stocké nulle part en clair. Révoquez-le (il est dans la liste, « jamais utilisé ») et créez-en un autre.

Pourquoi « jamais utilisé » alors que ma CI tourne ?

La CI utilise un autre jeton — le préfixe affiché permet de comparer avec le début du secret dans votre CI — ou l'appel n'atteint pas PostShip (401 sur un jeton mal collé ne compte pas comme une utilisation).

Puis-je donner un jeton à un collaborateur ?

Non : un jeton engage votre compte et vos projets. Invitez-le sur le projet depuis Équipe ; il créera son propre jeton, qui ne verra que ce qu'il a le droit de voir.