Authentification

Jetons porteurs

Chaque route sauf /health, /api/v1/openapi.json, /api/v1/docs et /api/v1/token exige un jeton porteur.

Authorization: Bearer <token>

Les jetons sont conservés dans le trousseau du système d’exploitation, avec une étiquette, une portée et une durée de vie facultative. Cette documentation ne décrit pas la forme d’un jeton — traite-le comme une chaîne opaque, et range-le comme n’importe quel autre secret.

En obtenir un

Depuis la ligne de commande :

tcc config create-api-token --scope full

Ou via HTTP, depuis la machine elle-même :

POST /api/v1/token
{ "name": "my-integration", "scope": "full" }

Cette route n’exige aucun jeton. Elle n’est sûre que parce que le serveur se lie à la boucle locale, donc tout ce qui peut l’atteindre se trouve déjà sur la machine. La réponse porte le jeton et sa portée.

Via HTTP, cette réponse est la seule fois où le jeton est montré : GET /api/v1/api-tokens les liste masqués. La ligne de commande peut encore révéler un jeton stocké à la personne présente sur la machine, ce qui explique pourquoi le trousseau est la frontière qui compte.

GET et POST sur /api/v1/api-tokens listent et créent des jetons ; DELETE /api/v1/api-tokens/{id} en révoque un.

Les trois portées

Un jeton porte l’une de trois portées. La portée est appliquée de façon centrale, d’après la méthode HTTP et le chemin, avant qu’un gestionnaire ne s’exécute.

Portée	Peut faire
read	N’importe quel GET en dehors des routes de gestion
write	La même chose, plus les écritures sur tes propres données
full	Tout, y compris la gestion d’organisation et la gestion des jetons

Gestion signifie /api/v1/org/members, /api/v1/org/groups, /api/v1/org/alerts et /api/v1/api-tokens. Elles nécessitent full sur chaque méthode, lectures comprises. Rien d’autre ne nécessite full — le reste des routes d’organisation, l’activité et les analyses y compris, sont des lectures ordinaires.

Donne à une intégration la portée la plus étroite qui fait son travail. Un script de reporting veut read ; il sera alors refusé s’il essaie un jour de supprimer quelque chose.

Refus

Un jeton manquant ou invalide donne 401. Un jeton valide dont la portée est trop étroite donne 403, avec un corps nommant la portée que tu as, la requête que tu as faite et la portée qu’il faudrait :

{
  "error": "insufficient_scope",
  "message": "Token scope 'read' cannot perform DELETE /api/v1/tags/abc. Requires write or full scope.",
  "required_scope": "write or full"
}

Révoquer un jeton est immédiat : supprime-le via /api/v1/api-tokens/{id} et la requête suivante qui le porte est refusée.