Gérer Caputchin depuis l'API

Tout ce que tu peux faire dans le tableau de bord, hors facturation, tu peux aussi le faire depuis du code. Caputchin expose une seule API de gestion, et trois surfaces reposent dessus : cette API HTTP directement, le serveur MCP pour les agents IA, et le provider Terraform et OpenTofu pour l'infrastructure-as-code. Elles ne diffèrent qu'au bord ; la même validation, les mêmes permissions et la même journalisation d'audit s'appliquent quelle que soit celle que tu utilises.

Les trois s'authentifient avec le même identifiant : un jeton d'accès que tu génères une fois.

Génère un jeton d'accès

Tu envoies le jeton comme en-tête Bearer. Il y a deux types, couverts en entier sous Personal Access Token et jetons d'équipe :

Jeton	Portée	Génère-le
Personal Access Token	Maître sur tout ton compte	Paramètres du compte. Gratuit, un par compte.
Troop Access Token	Seulement les équipes auxquelles il est attaché, avec les permissions accordées	La page des jetons d'une équipe. Prend un siège.

Utilise un Personal Access Token pour ta propre automatisation pleine-compte ; utilise un jeton d'équipe pour un accès limité et de moindre privilège (un job CI qui ne touche qu'une équipe). Les deux fonctionnent partout ci-dessous. La valeur du jeton est montrée une fois à la création, donc copie-la dans un coffre à secrets.

URL de base et auth

L'API de gestion est enracinée sur :

https://caputchin.com/api/v1/management

Chaque requête porte le jeton comme en-tête Bearer :

Authorization: Bearer cpt_pat_...

Les requêtes et réponses sont en JSON. Un appel que ton jeton n'est pas autorisé à faire renvoie 403 ; un jeton inconnu ou révoqué renvoie 401.

Un exemple concret : créer une clé de site

Disons que tu veux une nouvelle clé de site dans ton équipe shop-team. D'abord liste tes équipes pour trouver son id, puis crée la clé dedans.

# 1. Find the troop id.
curl -s https://caputchin.com/api/v1/management/troops \
  -H "Authorization: Bearer $CAPUTCHIN_MANAGEMENT_TOKEN"
# → { "troops": [ { "id": "troop_…", "name": "shop-team", … }, … ] }

# 2. Create a site key in that troop.
curl -s -X POST https://caputchin.com/api/v1/management/sites \
  -H "Authorization: Bearer $CAPUTCHIN_MANAGEMENT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "name": "shop-frontend", "troop_id": "troop_…" }'
# → { "id": "site_…", "key": "cpt_pub_…", "secret": "cpt_sec_…", … }

La réponse porte la key publique de la nouvelle clé et son secret. Le secret n'est montré qu'une fois, ici, donc capture-le maintenant ; tu vérifieras avec sur ton backend. Omets troop_id et la clé atterrit dans ton équipe Personnelle.

C'est tout le schéma : un jeton Bearer, un corps JSON, un appel par opération. Lister est GET, créer est POST, mettre à jour est PATCH ou PUT, retirer est DELETE, contre les chemins de ressources sous l'URL de base.

La référence complète

Chaque point de terminaison, avec ses paramètres, ses schémas de requête et de réponse, et un panneau « essaie-le » intégré qui s'authentifie avec ton jeton, est dans la référence interactive de l'API. Elle est générée à partir de la même spécification OpenAPI contre laquelle l'API est bâtie, donc elle ne dérive jamais de la surface en ligne. Pointe tes propres générateurs de clients vers la spec qui y est liée.

Voir aussi

Personal Access Token : l'identifiant maître et comment tracer son usage.
Utiliser le serveur MCP : la même API, pilotée par un agent IA.
Utiliser Terraform ou OpenTofu : la même API, en infrastructure-as-code.
Référence interactive de l'API : chaque point de terminaison et schéma.