---
type: how-to
title: 从 API 管理 Caputchin
summary: 用个人访问令牌做身份验证，直接通过 HTTP 驱动这一个管理 API，附一个完整示例和一个指向完整参考的链接。
---

你在仪表盘里能做的一切，除了账单，也都能从代码里做。Caputchin 暴露 **一个管理 API**，三个面坐落在它之上：直接的这个 HTTP API、给 AI 代理用的 [MCP 服务器](/docs/automation/mcp)，以及给基础设施即代码用的 [Terraform 和 OpenTofu 提供方](/docs/automation/terraform)。它们只在边缘有所不同；无论你用哪个，同样的校验、权限和审计日志都适用。

三者都用同一份凭据做身份验证：一个你铸造一次的访问令牌。

## 铸造一个访问令牌 [#mint-an-access-token]

你把令牌作为一个 `Bearer` 头发送。有两种，在 [个人访问令牌](/docs/account-management/personal-access-token) 和 [团队令牌](/docs/troops/tokens) 下有完整说明：

| 令牌 | 触及范围 | 在哪里铸造 |
|---|---|---|
| **个人访问令牌** | 主控你整个账户 | [账户设置](/docs/account-management/account-settings#account-access-token)。免费，每个账户一个。 |
| **团队访问令牌** | 只有它被附上的那些团队，带着授予的权限 | 一个团队的令牌页。占一个 [席位](/docs/troops/seats)。 |

用一个个人访问令牌来做你自己的全账户自动化；用一个团队令牌来做限定范围、最小权限的访问（一个只碰一个团队的 CI 任务）。下面任何地方两者都能用。令牌的值在创建时只 **显示一次**，所以把它复制进一个密钥存储里。

## 基址与认证

管理 API 的根是：

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

每个请求都把令牌作为一个 `Bearer` 头带上：

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

请求和响应是 JSON。一个你的令牌不被允许发起的调用返回 `403`；一个未知或已吊销的令牌返回 `401`。

## 一个完整示例：创建一个站点密钥

假设你想在你的 `shop-team` 团队里要一个新的站点密钥。先列出你的团队以找到它的 id，然后在它里面创建密钥。

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

响应携带这个新密钥的公开 `key` 和它的 `secret`。**密钥只显示一次**，就在这里，所以现在就抓住它；你会 [在你的后端用它核验](/docs/integration-guides/verify-on-your-backend)。省略 `troop_id`，密钥就落在你的个人团队里。

这就是整个套路：一个 `Bearer` 令牌、一个 JSON 体、每个操作一个调用。列出是 `GET`，创建是 `POST`，更新是 `PATCH` 或 `PUT`，移除是 `DELETE`，针对基址下的资源路径。

## 完整参考

每个端点，带它的参数、请求和响应模式，以及一个用你的令牌做身份验证的内置“试一试”面板，都在 [交互式 API 参考](/docs/api-reference) 里。它是从 API 所依据的同一份 OpenAPI 规范生成的，所以它绝不偏离线上的真实面。把你自己的客户端生成器指向那里链接的规范。

## 另见

- [个人访问令牌](/docs/account-management/personal-access-token)：那份主凭据，以及如何追踪它的使用。
- [使用 MCP 服务器](/docs/automation/mcp)：同样的 API，由一个 AI 代理驱动。
- [使用 Terraform 或 OpenTofu](/docs/automation/terraform)：同样的 API，作为基础设施即代码。
- [交互式 API 参考](/docs/api-reference)：每个端点和模式。