# API キーと開発者アクセス

Source: https://support.kapsulehost.com/ja-jp/developer-api-access

KapsuleHostはあなたに2つの開発者向けサーフェスを提供しています。アカウントをプログラムで読み取るためのスコープ付きAPIキーと、あなた自身のマシンとCIランナー上でTurborepoとNxビルドを高速化するリモートビルドキャッシュです。

どちらもデフォルトでは有効になっていません。どちらも**設定**から作成され、どちらもシークレットを正確に1回だけ提供します。

## APIキーの作成

APIキーは**設定**の下の**セキュリティ**に存在し、**APIキー**カード内にあります。

![KPanelセキュリティ設定のAPIキーカード（スコープチップが表示されている）](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp)

1. **設定**に移動し、**セキュリティ**をクリックします。
2. **APIキー**までスクロールして、**新しいキー**をクリックします。
3. キーに名前を付けます。フィールドは「キー名（例：マイオートメーションスクリプト）」と提案しています。名前はあなた用ですので、キーがどこで使用されるかを示すようにしてください。
4. スコープチップをクリックして、キーが何をできるかを選択します。3つの読み取りスコープがあらかじめ選択されています：`read:sites`、`read:email`、および`read:domains`。チップをクリックして追加または削除します。
5. **作成**をクリックします。

完全なキーは1回だけ表示されます。「今すぐコピー」という見出しの付いた緑色のパネルに表示されます。シークレットストアに直接コピーしてください。そのパネルを閉じると、キーは消えます。短いプレフィックスのみが保持され、それがリストが今後表示できるすべてです。

> **Warning:** キーは2回目以降に表示されることはなく、復元することもできません。失った場合は、そのキーを失効させ、新しいキーを作成してください。共有ドキュメント、チケット、コミット、またはチャットメッセージに貼り付けないでください。

**オーナー**および**管理者**ロールのみがキーを作成できます。他のロールを持つユーザーはパーミッションエラーを取得します。キーが作成されるとき、セキュリティアラートメールがそれを作成した人のアドレスに送信されるため、予期しないメールが届いた場合は即座に調査する価値があります。

## スコープ

7つのスコープが提供されています：

| スコープ | 権限 |
|---|---|
| `read:sites` | あなたのウェブサイトを読み取る |
| `write:sites` | ウェブサイトへの書き込み操作用に予約済み |
| `read:email` | あなたのメールボックスを読み取る |
| `write:email` | メールボックスへの書き込み操作用に予約済み |
| `read:domains` | あなたのドメインを読み取る |
| `write:domains` | ドメインへの書き込み操作用に予約済み |
| `read:billing` | 請求データの読み取り用に予約済み |

> **Note:** カスタマーAPIは現在読み取り専用です。`write:`スコープと`read:billing`はキー上で選択できますが、現在のところカスタマーエンドポイントはそれらを使用していないため、それらを付与しても何も変わりません。実際に必要な読み取りスコープのみを付与し、書き込みエンドポイントが公開されるときにキーを再検討してください。

## キーの使用

キーを`Authorization`ヘッダーのベアラートークンとして送信します。

```sh
curl https://kpanel.kapsulehost.com/api/v1/sites \
  -H "Authorization: Bearer YOUR_KEY_HERE"
```

3つのエンドポイントがカスタマーAPIキーを受け入れます：

| エンドポイント | 必要なスコープ | 返すもの |
|---|---|---|
| `GET /api/v1/sites` | `read:sites` | あなたのウェブサイト（ドメイン、アプリケーションタイプ、ステータス付き） |
| `GET /api/v1/domains` | `read:domains` | あなたのドメイン（ステータスと有効期限付き） |
| `GET /api/v1/mailboxes` | `read:email` | あなたのメールボックス |

キーなし、未知のキー、または失効したキーを持つリクエストは`401`を返します。必要なスコープを持たない有効なキーは`403`を返し、必要なスコープを指定するメッセージが表示されます。すべての成功した呼び出しはキーの最後使用タイムスタンプを更新します。

> **Tip:** やさしくポーリングしてください。これらのエンドポイントはライブアカウントデータを読み取り、それらに対する厳密なループは不正使用と区別がつきません。ダッシュボードが必要とするもの向けに1分1回が十分です。通常、1時間1回で十分です。

## キーの確認と失効

APIキーテーブルは各アクティブキーを**名前**、**プレフィックス**（キーの見える始まり）、および**スコープ**でリストします。行の最後の**失効**をクリックしてそれを無効化します。

> **Important:** 失効は直ちに有効になり、確認ダイアログはありません。そのキーを使用する次のリクエストは`401`で失敗します。失効したキーは復元できないため、クリックする前にそれを使用しているものを確認してください。

キーは**アカウント**に属し、それらを作成した人には属しません。[チームページ](https://support.kapsulehost.com/ja-jp/account-team-members)からチームメートを削除しても、彼らが作成したキーは失効しません。オフボーディングにキーレビューを組み込んでください：その人を削除してから、ここに来て、彼らが作成したものを失効させます。

キー作成と失効の両方は、[監査ログ](https://support.kapsulehost.com/ja-jp/account-audit-log)の`api_key.*`アクション下に記録され、アクターと発信元IPアドレスが記載されます。

## リモートビルドキャッシュ

設定レールの詳細グループの**開発者**ページは、**リモートビルドキャッシュ**を提供しています。パネルはそれを「マシンとCIパイプライン全体で分散キャッシュを共有することでTurborepoとNxビルドを高速化する方法」として説明しています。

1. **設定**に移動し、**開発者**をクリックします。
2. **リモートキャッシュを有効にする**をクリックします。
3. 「新しいトークンが生成されました。今すぐコピーしてください。二度と表示されません」というタイトルのパネルからトークンをコピーします。

その後、CI設定またはローカル`.env.local`に2つの環境変数を設定します：

```sh
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
```

チームIDはあなたのKapsuleHostアカウントIDで、同じページのセットアップ手順に表示されています。

ページはその独自の互換性を述べています：Turborepo 1.x以降、Nx 16以降、および同じリモートキャッシュプロトコルを実装する任意のツール。アーティファクトはアカウントごとに保存され、アカウント間で共有されることはありません。

カード上にさらに2つのコントロールがあります：

- **トークンをローテーション**すると、新しいトークンが発行され、古いトークンが無効になります。古いトークンを保持しているCIジョブはキャッシュの使用を停止するため、ローテーションとシークレットの更新を一緒に行います。
- **無効にする**とキャッシュが完全にオフになります。

## 2つの間での選択

それらは無関係な問題を解決し、互いに置き換えることはできません。

**APIキー**は、KapsuleHost外の何かがあなたのアカウントの状態を知る必要がある場合に使用します。あなたのサイトをリストするステータスボード、ドメインが近く有効期限切れになることを警告するスクリプト、インベントリエクスポート。

**リモートビルドキャッシュ**は、すべてのマシンとすべてのCI実行が同じ変更されていないパッケージを再構築するため、ビルドが遅い場合に使用します。ホストされたサイトとは無関係で、アカウントデータを読み取りません。

## トラブルシューティング

**すべてのリクエストが401を返します。** ヘッダーを`Authorization: Bearer <key>`として1つのスペースで送信したこと、キーをコピーするときに切り詰められていないこと、失効していないことを確認してください。キーの始まりを**プレフィックス**列と比較して、あなたが使用しようとしているキーを確認していることを確認します。

**リクエストがスコープを指定する403を返します。** キーはそのスコープを実行していません。スコープはキーの作成時に固定されるため、正しいスコープで置き換えを作成し、古いものを失効させます。

**APIキーカードが表示されません。** セキュリティページの上にあり、開発者ページではありません。開発者ページはビルドキャッシュのみを保持しています。

**新しいキーボタンが何もしません。** あなたのロールは管理者以下です。オーナーまたは管理者に尋ねてください。

**ビルドはキャッシュにヒットしていません。** `TURBO_TOKEN`と`TURBO_TEAM`の両方がビルド環境に存在すること、設定してからトークンが回転されていないこと、ページがまだ**アクティブ**バッジを表示していることを確認してください。

**私が作成していないキーが表示されました。** それを侵害として扱います。それを失効させてから、[アカウントセキュリティ](https://support.kapsulehost.com/ja-jp/account-security)を確認し、[監査ログ](https://support.kapsulehost.com/ja-jp/account-audit-log)で他に何が変更されたかを確認します。