---
type: how-to
title: Gérer Caputchin depuis l'API
summary: Authentifie-toi avec un Personal Access Token et pilote l'unique API de gestion directement en HTTP, avec un exemple concret et un lien vers la référence complète.
---

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](/docs/automation/mcp) pour les agents IA, et le [provider Terraform et OpenTofu](/docs/automation/terraform) 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 [#mint-an-access-token]

Tu envoies le jeton comme en-tête `Bearer`. Il y a deux types, couverts en entier sous [Personal Access Token](/docs/account-management/personal-access-token) et [jetons d'équipe](/docs/troops/tokens) :

| Jeton | Portée | Génère-le |
|---|---|---|
| **Personal Access Token** | Maître sur tout ton compte | [Paramètres du compte](/docs/account-management/account-settings#account-access-token). 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](/docs/troops/seats). |

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://api.caputchin.com/v1/management
```

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

```http
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.

```bash
# 1. Find the troop id.
curl -s https://api.caputchin.com/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://api.caputchin.com/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](/docs/integration-guides/verify-on-your-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](/docs/api-reference). 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](/docs/account-management/personal-access-token) : l'identifiant maître et comment tracer son usage.
- [Utiliser le serveur MCP](/docs/automation/mcp) : la même API, pilotée par un agent IA.
- [Utiliser Terraform ou OpenTofu](/docs/automation/terraform) : la même API, en infrastructure-as-code.
- [Référence interactive de l'API](/docs/api-reference) : chaque point de terminaison et schéma.