---
type: how-to
title: Gestiona Caputchin desde la API
summary: Autentícate con un personal access token y conduce la única API de gestión directamente sobre HTTP, con un ejemplo trabajado y un enlace a la referencia completa.
---

Todo lo que puedes hacer en el dashboard, salvo la facturación, puedes hacerlo también desde código. Caputchin expone **una API de gestión**, y tres superficies se asientan encima de ella: esta API HTTP directamente, el [servidor MCP](/docs/automation/mcp) para agentes de IA, y el [proveedor de Terraform y OpenTofu](/docs/automation/terraform) para infraestructura como código. Difieren solo en el borde; la misma validación, los mismos permisos y el mismo audit logging aplican cualquiera que uses.

Las tres se autentican con la misma credencial: un access token que acuñas una vez.

## Acuña un access token [#mint-an-access-token]

Envías el token como un header `Bearer`. Hay dos tipos, cubiertos por completo bajo [personal access token](/docs/account-management/personal-access-token) y [tokens de equipo](/docs/troops/tokens):

| Token | Alcance | Acúñalo |
|---|---|---|
| **Personal access token** | Maestro sobre toda tu cuenta | [Ajustes de cuenta](/docs/account-management/account-settings#account-access-token). Gratis, uno por cuenta. |
| **Troop access token** | Solo los equipos a los que está adjunto, con los permisos concedidos | La página de tokens de un equipo. Ocupa un [asiento](/docs/troops/seats). |

Usa un personal access token para tu propia automatización de toda la cuenta; usa un token de equipo para acceso acotado, de mínimo privilegio (un job de CI que solo toca un equipo). Cualquiera funciona en todo lo de abajo. El valor del token se muestra **una vez** al crearlo, así que cópialo a un almacén de secretos.

## URL base y auth

La API de gestión tiene su raíz en:

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

Cada petición lleva el token como un header `Bearer`:

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

Las peticiones y respuestas son JSON. Una llamada que tu token no tiene permitido hacer devuelve `403`; un token desconocido o revocado devuelve `401`.

## Un ejemplo trabajado: crear una clave de sitio

Digamos que quieres una nueva clave de sitio en tu equipo `shop-team`. Primero lista tus equipos para encontrar su id, luego crea la clave en él.

```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 respuesta lleva la `key` pública de la nueva clave y su `secret`. El **secreto se muestra una vez**, aquí, así que captúralo ahora; lo usarás para [verificar en tu backend](/docs/integration-guides/verify-on-your-backend). Omite `troop_id` y la clave aterriza en tu equipo Personal.

Ese es el patrón entero: un token `Bearer`, un cuerpo JSON, una llamada por operación. Listar es `GET`, crear es `POST`, actualizar es `PATCH` o `PUT`, quitar es `DELETE`, contra las rutas de recurso bajo la URL base.

## La referencia completa

Cada endpoint, con sus parámetros, sus esquemas de petición y respuesta, y un panel integrado de "pruébalo" que se autentica con tu token, está en la [referencia interactiva de la API](/docs/api-reference). Se genera a partir de la misma especificación OpenAPI contra la que se construye la API, así que nunca se desvía de la superficie real. Apunta tus propios generadores de cliente a la spec enlazada ahí.

## Véase también

- [Personal access token](/docs/account-management/personal-access-token): la credencial maestra y cómo rastrear su uso.
- [Usa el servidor MCP](/docs/automation/mcp): la misma API, conducida por un agente de IA.
- [Usa Terraform o OpenTofu](/docs/automation/terraform): la misma API, como infraestructura como código.
- [Referencia interactiva de la API](/docs/api-reference): cada endpoint y esquema.