Jetons d'API

Cette page sert à créer un jeton d’API pour des scripts, des pipelines d’intégration continue et des agents d’IA. Elle explique aussi comment approuver une demande de connexion d’appareil lancée par un script ou un SDK.

Un jeton d’API appelle l’API sans votre mot de passe. Chaque jeton ne peut faire que ce que ses portées permettent. Il expire à la date que vous choisissez, et vous pouvez le révoquer en tout temps.

Deux choses à avoir sous la main

Vérifiez que :

• vous pouvez vous connecter au tableau de bord, y compris avec la vérification en deux étapes si elle est activée;
• vous savez quels scripts ou agents utiliseront le jeton, pour choisir les portées les plus étroites possible.

Tous les forfaits permettent de créer des jetons d’API. Votre forfait détermine les portées que vous pouvez accorder et le nombre de jetons actifs à la fois. Avec le forfait Free, vous avez droit à un seul jeton actif, limité à la lecture des hubs, à la gestion des clients et à votre mémoire; le sélecteur affiche les autres portées comme verrouillées, avec un lien pour passer à un forfait supérieur. Révoquer un jeton libère sa place tout de suite. Le tableau des forfaits présente chaque forfait.

Créer un jeton d’API

1. Ouvrez API tokens (jetons d’API). La page se trouve dans la section du compte de la navigation du tableau de bord.
2. Choisissez Create token. Donnez-lui un Token name clair, comme « CI deploy script ».
3. Choisissez les portées. Cochez uniquement les accès dont le script a besoin. Moins il y a de portées, moins le risque est grand si le jeton fuit.
4. Choisissez une échéance. Choisissez 30, 90 ou 365 jours, ou fixez une date personnalisée. Plus c’est court, plus c’est sûr.
5. Copiez le jeton affiché sous « Copy your token now ». Vous ne reverrez plus ce jeton. Rangez-le dans un gestionnaire de secrets ou un secret d’intégration continue, puis choisissez I saved my token.

Un compte Free a une place de jeton et un quota quotidien. La liste reste vide tant que vous n’en créez pas.

Le jeton commence par tvpat_. Le tableau ne garde que ce court préfixe : le secret complet n’existe que dans votre copie.

Choisir les bonnes portées

Portée	Ce qu’elle permet
hubs:read	Voir vos hubs.
hubs:write	Créer et mettre à jour des hubs.
hubs:preview	Prévisualiser les réponses d’un hub.
hubs:inspect	Inspecter le détail du runtime d’un hub.
hubs:runtime-inspect	Inspecter l’inventaire du runtime d’un hub public qui ne vous appartient pas.
clients:read	Voir les connexions de clients.
clients:write	Créer des connexions de clients.
acls:read	Voir les règles d’accès.
acls:write	Gérer les règles d’accès.
memory:read	Lire votre mémoire enregistrée. Tous les forfaits.
memory:write	Écrire dans votre mémoire enregistrée. Tous les forfaits; Free conserve un seul élément de mémoire.

Pour un agent d’IA qui utilise le serveur MCP, l’ensemble habituel est hubs:read, clients:write, memory:read et memory:write. Tous les forfaits, y compris Free, peuvent accorder cet ensemble. Avec Free, l’agent ne peut enregistrer qu’un seul élément de mémoire.

Les portées décident des actions qu’un jeton peut effectuer. Pour limiter les hubs sur lesquels il peut agir, consultez Restreindre un jeton à certains hubs.

Restreindre un jeton à certains hubs

Par défaut, un jeton peut agir sur tous vos hubs. À la création d’un jeton, vous pouvez plutôt le limiter à certains hubs : choisissez ceux qu’il peut utiliser, ou laissez la sélection vide pour les garder tous. Vous ne pouvez choisir que des hubs qui vous appartiennent. L’option est offerte avec tous les forfaits, puisqu’elle ne fait que restreindre l’accès.

Un jeton restreint fonctionne sur les hubs choisis, et sur aucun autre. Sur ces hubs, il peut encore faire le travail ciblé que ses portées permettent :

• lire, mettre à jour, publier et évaluer le hub, et vérifier les capacités de son runtime;
• gérer les règles d’accès de ce hub;
• lire et écrire la mémoire de ce hub.

Quand il liste les hubs, il ne voit que ceux qui ont été choisis, et il ne peut pas créer de nouveaux hubs. Le travail qui n’est pas lié à un hub, comme votre mémoire personnelle ou celle de l’espace de travail, suit toujours les portées du jeton. La restriction par hub filtre les hubs que le jeton peut atteindre; elle ne remplace pas ce que ses portées permettent.

Le tableau des jetons indique les hubs de chaque jeton. Vous distinguez ainsi un jeton restreint d’un jeton qui atteint tous les hubs.

Surveiller et révoquer les jetons

Pour chaque jeton, le tableau affiche les colonnes Name, Token, Scopes, Created, Expires, Last used, Requests (24h) et Status. Le statut est Active, Expired ou Revoked. Utilisez Show revoked pour inclure les lignes révoquées.

Last used et Requests (24h) se mettent à jour quand le jeton s’authentifie, en une trentaine de secondes environ. Un jeton censé être inactif qui montre une utilisation récente vaut donc la peine d’être vérifié.

Votre forfait fixe pour chaque jeton un débit de requêtes et des quotas d’appels. Au-delà de l’une de ces limites, vous recevez une réponse HTTP 429 avec un en-tête Retry-After qui indique quand réessayer : la minute suivante pour le débit, ou le jour ou le mois UTC suivant pour un quota. Le tableau des jetons montre l’utilisation du jour par rapport à votre quota quotidien.

Les jetons selon le forfait

La gamme Home énumère explicitement chaque portée standard. Les forfaits Work permettent toutes les portées standard par défaut. Un tiret dans la colonne du débit signifie qu’il n’y a pas de plafond par minute.

Forfait	Jetons actifs	Portées	Débit	Par jour	Par mois
Free	1	hubs:read, clients:read, clients:write, memory:read, memory:write	60/min	10 000	200 000
Home	5	Toutes les portées standard	120/min	20 000	400 000
Family	10	Toutes les portées standard	240/min	60 000	1 200 000
Workspace	100	Toutes les portées standard	—	100 000	2 000 000
Business, Civic et Pilot	100	Toutes les portées standard	—	1 000 000	20 000 000
Site Pack, Municipality et Private Edge	Indiqué dans Billing	Toutes les portées standard	Indiqué dans Billing	Indiqué dans Billing	Indiqué dans Billing
Enterprise	Sur mesure	Toutes les portées standard	Sur mesure	Sur mesure	Sur mesure

Les portées standard sont les onze de la section Choisir les bonnes portées. Pour savoir ce que couvre la gamme Home, consultez Développeurs du forfait Home.

Les anciens forfaits qui ne sont plus vendus gardent leurs limites de jetons. Un forfait que Thalovant attribue directement à un compte affiche ses propres limites sur cette page et dans Billing.

Pour révoquer un jeton, choisissez l’action Revoke token sur sa ligne, puis confirmez. Tout ce qui utilise encore ce jeton cesse de fonctionner immédiatement, et la révocation est irréversible. Si vous perdez le secret d’un jeton, révoquez l’ancien et créez-en un nouveau; le secret ne peut pas être affiché de nouveau.

Approuver une connexion d’appareil

Quand un script ou un SDK se connecte sans mot de passe, il affiche un code court comme GHXK-PQRS et l’adresse https://dash.thalovant.com/activate.

1. Ouvrez la page activate. Connectez-vous d’abord si on vous le demande, avec votre méthode habituelle, y compris la connexion Google ou le code de votre application d’authentification.
2. Entrez le code de l’appareil. La page le recherche dès que le code est complet. Les minuscules et un tiret manquant sont acceptés. Les codes expirent après environ 15 minutes.
3. Examinez la demande. La page indique quel appareil ou script veut accéder à votre compte et liste ce qu’il pourra faire.
4. Choisissez Approve access ou Deny. N’approuvez que les demandes que vous avez lancées vous-même.
5. Revenez à l’appareil. Après Access approved, l’appareil termine sa connexion de lui-même.

L’approbation crée un jeton d’API dont les portées se limitent aux accès listés sur la page d’approbation. Il apparaît dans votre tableau des jetons comme n’importe quel autre jeton : vous pouvez suivre sa dernière utilisation et le révoquer plus tard. Les limites de portées et de jetons de votre forfait s’appliquent aussi. La page vous prévient quand une demande réclame des portées que votre forfait ne peut pas accorder, ou quand vous devez d’abord révoquer un jeton existant.

Attention

N’approuvez qu’une connexion d’appareil que vous avez lancée vous-même. Si la demande est inattendue, choisissez Deny; un code refusé ne peut plus servir.

Quand le jeton est en place

La tâche est terminée quand :

• le secret du jeton est rangé en lieu sûr et la ligne affiche Active;
• le script ou l’agent réussit un appel et Last used se met à jour;
• pour une connexion d’appareil, l’appareil indique qu’il est connecté après Access approved.

Si une portée est verrouillée ou qu’un jeton échoue

Symptôme	Première vérification
Une portée est verrouillée dans le sélecteur	Votre forfait ne l’inclut pas. Ouvrez Billing pour passer à un forfait supérieur, ou choisissez une portée plus étroite.
Your plan’s API token limit is reached	Révoquez un jeton existant pour libérer une place, ou passez à un forfait supérieur pour avoir plus de jetons actifs.
Code not found or expired sur la page activate	Demandez un nouveau code à l’appareil ou au script, et entrez-le dans les 15 minutes.
Un jeton cesse soudainement de fonctionner	Vérifiez son Status; les jetons expirés et révoqués sont refusés.
Vous avez perdu le secret du jeton	Créez un nouveau jeton, mettez à jour le script, puis révoquez l’ancien jeton.
Un appel échoue avec une erreur de portée	Créez un nouveau jeton qui inclut la portée dont l’appel a besoin.
Un jeton restreint ne peut pas agir sur un hub	Ce hub ne figure pas dans la liste autorisée du jeton, ou le jeton est restreint et ne peut pas créer de hubs. Utilisez un jeton qui inclut le hub, ou un jeton sans restriction de hub.
Les appels renvoient 429 avec token_rate_limited	Le jeton a atteint la limite de débit par minute de son forfait. Attendez l’intervalle indiqué par Retry-After, ou passez à un forfait supérieur.
Les appels renvoient 429 avec token_quota_exceeded	Le jeton a épuisé son quota d’appels quotidien ou mensuel. L’erreur précise lequel, et Retry-After pointe vers le jour ou le mois UTC suivant.

Utiliser le jeton dans un SDK