---
type: how-to
title: Manage Caputchin from the API
summary: Authenticate with a personal access token and drive the one management API directly over HTTP, with a worked example and a link to the full reference.
---

Everything you can do in the dashboard, short of billing, you can also do from code. Caputchin exposes **one management API**, and three surfaces sit on top of it: this HTTP API directly, the [MCP server](/docs/automation/mcp) for AI agents, and the [Terraform and OpenTofu provider](/docs/automation/terraform) for infrastructure-as-code. They differ only at the edge; the same validation, permissions, and audit logging apply whichever you use.

All three authenticate with the same credential: an access token you mint once.

## Mint an access token [#mint-an-access-token]

You send the token as a `Bearer` header. There are two kinds, covered in full under [personal access token](/docs/account-management/personal-access-token) and [troop tokens](/docs/troops/tokens):

| Token | Reach | Mint it |
|---|---|---|
| **Personal access token** | Master over your whole account | [Account settings](/docs/account-management/account-settings#account-access-token). Free, one per account. |
| **Troop access token** | Only the troops it is attached to, with granted permissions | A troop's tokens page. Takes a [seat](/docs/troops/seats). |

Use a personal access token for your own full-account automation; use a troop token for scoped, least-privilege access (a CI job that only touches one troop). Either works everywhere below. The token value is shown **once** at creation, so copy it into a secret store.

## Base URL and auth

The management API is rooted at:

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

Every request carries the token as a `Bearer` header:

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

Requests and responses are JSON. A call your token is not allowed to make returns `403`; an unknown or revoked token returns `401`.

## A worked example: create a site key

Say you want a new site key in your `shop-team` troop. First list your troops to find its id, then create the key in it.

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

The response carries the new key's public `key` and its `secret`. The **secret is shown once**, here, so capture it now; you will [verify with it on your backend](/docs/integration-guides/verify-on-your-backend). Omit `troop_id` and the key lands in your Personal troop.

That is the whole pattern: a `Bearer` token, a JSON body, one call per operation. Listing is `GET`, creating is `POST`, updating is `PATCH` or `PUT`, removing is `DELETE`, against the resource paths under the base URL.

## The full reference

Every endpoint, with its parameters, request and response schemas, and a built-in "try it" panel that authenticates with your token, is in the [interactive API reference](/docs/api-reference). It is generated from the same OpenAPI specification the API is built against, so it never drifts from the live surface. Point your own client generators at the spec linked there.

## See also

- [Personal access token](/docs/account-management/personal-access-token): the master credential and how to trace its use.
- [Use the MCP server](/docs/automation/mcp): the same API, driven by an AI agent.
- [Use Terraform or OpenTofu](/docs/automation/terraform): the same API, as infrastructure-as-code.
- [Interactive API reference](/docs/api-reference): every endpoint and schema.