---
type: how-to
title: Gerencie o Caputchin pela API
summary: Autentique-se com um token de acesso pessoal e conduza a única API de gestão diretamente por HTTP, com um exemplo prático e um link para a referência completa.
---

Tudo o que você consegue fazer no painel, salvo faturamento, você também consegue fazer a partir do código. O Caputchin expõe **uma API de gestão**, e três superfícies ficam em cima dela: esta API HTTP diretamente, o [servidor MCP](/docs/automation/mcp) para agentes de IA, e o [provedor Terraform e OpenTofu](/docs/automation/terraform) para infraestrutura como código. Elas diferem só na borda; a mesma validação, permissões e registro de auditoria se aplicam qualquer que seja a que você use.

As três se autenticam com a mesma credencial: um token de acesso que você acune uma vez.

## Acune um token de acesso [#mint-an-access-token]

Você envia o token como um cabeçalho `Bearer`. Há dois tipos, cobertos por completo em [token de acesso pessoal](/docs/account-management/personal-access-token) e [tokens de equipe](/docs/troops/tokens):

| Token | Alcance | Acune-o |
|---|---|---|
| **Token de acesso pessoal** | Mestre sobre toda a sua conta | [Configurações da conta](/docs/account-management/account-settings#account-access-token). Grátis, um por conta. |
| **Token de acesso de equipe** | Só as equipes a que está ligado, com as permissões concedidas | A página de tokens de uma equipe. Ocupa um [assento](/docs/troops/seats). |

Use um token de acesso pessoal para sua própria automação de conta inteira; use um token de equipe para acesso delimitado, de menor privilégio (um job de CI que só toca uma equipe). Qualquer um funciona em todo o resto abaixo. O valor do token é mostrado **uma vez** na criação, então copie-o para um cofre de segredos.

## URL base e autenticação

A API de gestão tem raiz em:

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

Toda requisição carrega o token como um cabeçalho `Bearer`:

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

Requisições e respostas são JSON. Uma chamada que seu token não tem permissão de fazer retorna `403`; um token desconhecido ou revogado retorna `401`.

## Um exemplo prático: criar uma chave de site

Digamos que você queira uma nova chave de site na sua equipe `shop-team`. Primeiro liste suas equipes para achar o id dela, depois crie a chave nela.

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

A resposta carrega a `key` pública da nova chave e seu `secret`. O **segredo é mostrado uma vez**, aqui, então capture-o agora; você vai [verificar com ele no seu backend](/docs/integration-guides/verify-on-your-backend). Omita `troop_id` e a chave cai na sua equipe Pessoal.

Esse é o padrão inteiro: um token `Bearer`, um corpo JSON, uma chamada por operação. Listar é `GET`, criar é `POST`, atualizar é `PATCH` ou `PUT`, remover é `DELETE`, contra os caminhos de recurso sob a URL base.

## A referência completa

Cada endpoint, com seus parâmetros, esquemas de requisição e resposta, e um painel embutido de "experimente" que se autentica com seu token, está na [referência interativa da API](/docs/api-reference). Ela é gerada da mesma especificação OpenAPI contra a qual a API é construída, então nunca desvia da superfície ativa. Aponte seus próprios geradores de cliente para a spec linkada ali.

## Veja também

- [Token de acesso pessoal](/docs/account-management/personal-access-token): a credencial mestre e como rastrear seu uso.
- [Use o servidor MCP](/docs/automation/mcp): a mesma API, conduzida por um agente de IA.
- [Use Terraform ou OpenTofu](/docs/automation/terraform): a mesma API, como infraestrutura como código.
- [Referência interativa da API](/docs/api-reference): cada endpoint e esquema.