---
type: how-to
title: API から Caputchin を管理する
summary: Personal Access Tokenで認証し、唯一の管理 API を HTTP 越しに直接動かします。実例と、完全なリファレンスへのリンク付き。
---

ダッシュボードでできることは、請求を除き、コードからもすべてできます。Caputchin は **唯一の管理 API** を公開し、その上に 3 つの面が乗ります。この HTTP API を直接、AI エージェント向けの [MCP サーバー](/docs/automation/mcp)、そして infrastructure-as-code 向けの [Terraform と OpenTofu のプロバイダー](/docs/automation/terraform) です。それらは縁でしか違いません。どれを使っても、同じ検証、権限、監査ログが適用されます。

3 つすべてが同じ資格情報で認証します。一度発行するアクセストークンです。

## アクセストークンを発行する [#mint-an-access-token]

トークンは `Bearer` ヘッダーとして送ります。2 種類あり、[Personal Access Token](/docs/account-management/personal-access-token) と [チームトークン](/docs/troops/tokens) の下で完全に扱われます：

| トークン | 到達範囲 | 発行する場所 |
|---|---|---|
| **Personal Access Token** | あなたのアカウント全体へのマスター | [アカウント設定](/docs/account-management/account-settings#account-access-token)。無料、アカウントにつき 1 つ。 |
| **Troop Access Token** | 紐づけられたチームだけ、付与された権限で | チームのトークンページ。[シート](/docs/troops/seats) を取る。 |

あなた自身のアカウント全体の自動化にはPersonal Access Tokenを、スコープづけされた最小権限のアクセス（1 つのチームだけに触れる CI ジョブ）にはチームトークンを使ってください。どちらも以下のすべてで動きます。トークンの値は作成時に **一度だけ** 表示されるので、シークレットストアにコピーしてください。

## ベース URL と認証

管理 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 のボディ、操作ごとに 1 回の呼び出し。一覧は `GET`、作成は `POST`、更新は `PATCH` か `PUT`、削除は `DELETE` を、ベース URL の下のリソースパスに対して行います。

## 完全なリファレンス

すべてのエンドポイントを、そのパラメータ、リクエストとレスポンスのスキーマ、そしてあなたのトークンで認証する組み込みの「試す」パネルとともに、[インタラクティブ API リファレンス](/docs/api-reference) で示します。それは API が作られているのと同じ OpenAPI 仕様から生成されるので、ライブの面から決してずれません。あなた自身のクライアントジェネレーターを、そこにリンクされた仕様に向けてください。

## あわせて読む

- [Personal Access Token](/docs/account-management/personal-access-token)：マスター資格情報と、その使用を追跡する方法。
- [MCP サーバーを使う](/docs/automation/mcp)：同じ API を、AI エージェントが駆動する。
- [Terraform または OpenTofu を使う](/docs/automation/terraform)：同じ API を、infrastructure-as-code として。
- [インタラクティブ API リファレンス](/docs/api-reference)：すべてのエンドポイントとスキーマ。