---
type: how-to
title: Caputchin über die API verwalten
summary: Authentifizier dich mit einem Personal Access Token und steuer die eine Management-API direkt über HTTP, mit einem ausgearbeiteten Beispiel und einem Link zur vollständigen Referenz.
---

Alles, was du im Dashboard tun kannst, außer Abrechnung, kannst du auch aus Code tun. Caputchin stellt **eine Management-API** bereit, und drei Flächen sitzen darauf: diese HTTP-API direkt, der [MCP-Server](/docs/automation/mcp) für KI-Agenten und der [Terraform- und OpenTofu-Provider](/docs/automation/terraform) für Infrastructure-as-Code. Sie unterscheiden sich nur am Rand; dieselbe Validierung, dieselben Berechtigungen und dasselbe Audit-Logging gelten, welche du auch nutzt.

Alle drei authentifizieren sich mit derselben Anmeldedatei: einem Access Token, das du einmal prägst.

## Ein Access Token prägen [#mint-an-access-token]

Du sendest den Token als `Bearer`-Header. Es gibt zwei Arten, in voller Länge behandelt unter [Personal Access Token](/docs/account-management/personal-access-token) und [Team-Tokens](/docs/troops/tokens):

| Token | Reichweite | Präg es |
|---|---|---|
| **Personal Access Token** | Master über dein ganzes Konto | [Kontoeinstellungen](/docs/account-management/account-settings#account-access-token). Kostenlos, einer pro Konto. |
| **Troop Access Token** | Nur die Teams, an die es angehängt ist, mit gewährten Berechtigungen | Die Token-Seite eines Teams. Nimmt einen [Sitz](/docs/troops/seats). |

Nimm ein Personal Access Token für deine eigene vollständige Konto-Automatisierung; nimm ein Team-Token für eingeschränkten Least-Privilege-Zugriff (ein CI-Job, der nur ein Team berührt). Beide funktionieren überall unten. Der Token-Wert wird **einmal** bei der Erstellung gezeigt, also kopier ihn in einen Secret-Store.

## Basis-URL und Auth

Die Management-API ist gewurzelt bei:

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

Jede Anfrage trägt den Token als `Bearer`-Header:

```http
Authorization: Bearer cpt_pat_...
```

Anfragen und Antworten sind JSON. Ein Aufruf, den dein Token nicht machen darf, gibt `403` zurück; ein unbekannter oder widerrufener Token gibt `401` zurück.

## Ein ausgearbeitetes Beispiel: einen Site-Key erstellen

Sagen wir, du willst einen neuen Site-Key in deinem `shop-team`-Team. Liste zuerst deine Teams auf, um die id zu finden, dann erstell den Key darin.

```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_…", … }
```

Die Antwort trägt den öffentlichen `key` des neuen Keys und sein `secret`. Das **Secret wird einmal gezeigt**, hier, also fang es jetzt ein; du wirst [damit auf deinem Backend verifizieren](/docs/integration-guides/verify-on-your-backend). Lass `troop_id` weg, und der Key landet in deinem persönlichen Team.

Das ist das ganze Muster: ein `Bearer`-Token, ein JSON-Body, ein Aufruf pro Operation. Auflisten ist `GET`, Erstellen ist `POST`, Aktualisieren ist `PATCH` oder `PUT`, Entfernen ist `DELETE`, gegen die Ressourcen-Pfade unter der Basis-URL.

## Die vollständige Referenz

Jeder Endpunkt, mit seinen Parametern, Anfrage- und Antwort-Schemas und einem eingebauten "Try it"-Panel, das sich mit deinem Token authentifiziert, ist in der [interaktiven API-Referenz](/docs/api-reference). Sie wird aus derselben OpenAPI-Spezifikation generiert, gegen die die API gebaut ist, also driftet sie nie von der Live-Fläche ab. Richte deine eigenen Client-Generatoren auf die dort verlinkte Spec.

## Siehe auch

- [Personal Access Token](/docs/account-management/personal-access-token): die Master-Anmeldedatei und wie du ihre Nutzung nachverfolgst.
- [Den MCP-Server nutzen](/docs/automation/mcp): dieselbe API, gesteuert von einem KI-Agenten.
- [Terraform oder OpenTofu nutzen](/docs/automation/terraform): dieselbe API, als Infrastructure-as-Code.
- [Interaktive API-Referenz](/docs/api-reference): jeder Endpunkt und jedes Schema.