アカウント
API キーと開発者アクセス
Kapsule gives you two developer surfaces: scoped API keys for reading your account programmatically, and a remote build cache that speeds up Turborepo and Nx builds on your own machines and CI…
Kapsule は2つの開発者向けサーフェスを提供します。アカウント情報をプログラムで読み取るためのスコープ付き API キー、および Turborepo と Nx ビルドを自分のマシンと CI ランナー上で高速化するリモートビルドキャッシュです。
どちらもデフォルトでは有効になっていません。どちらも Settings から作成され、どちらも秘密鍵を正確に1回だけ提供します。
API キーの作成
API キーは Settings の下の Security にある API Keys カードにあります。
- Settings に移動して、Security をクリックします。
- API Keys までスクロールして、New key をクリックします。
- キーに名前を付けます。フィールドには「Key name (e.g. My automation script)」と表示されます。名前はあなた用なので、キーがどこで使用されるかを明示してください。
- スコープチップをクリックして、キーが実行できる操作を選択します。3つの読み取りスコープが事前選択されています:
read:sites、read:email、read:domains。チップをクリックして追加または削除します。 - Create をクリックします。
完全なキーは1回だけ表示されます。「Copy now」というヘッダーの付いた緑色のパネルに表示されます。すぐにシークレットストレージにコピーしてください。そのパネルを閉じると、キーは消えます。短いプレフィックスのみが保持され、これがリストに再度表示されるすべてです。
キーは2回目以降は表示されず、復旧することはできません。紛失した場合は、そのキーを取り消して新しいものを作成してください。共有ドキュメント、チケット、コミット、またはチャットメッセージに貼り付けないでください。
Owner と Admin ロールだけがキーを作成できます。その他のロールは権限エラーが表示されます。キーが作成されると、セキュリティ警告メールが作成者のアドレスに送信されるため、予期しないメールが届いた場合はすぐに調査する価値があります。
スコープ
7つのスコープが提供されています:
| スコープ | 権限内容 |
|---|---|
read:sites | ウェブサイトの読み取り |
write:sites | ウェブサイトへの書き込み操作用に予約済み |
read:email | メールボックスの読み取り |
write:email | メールボックスへの書き込み操作用に予約済み |
read:domains | ドメインの読み取り |
write:domains | ドメインへの書き込み操作用に予約済み |
read:billing | 請求データの読み取り用に予約済み |
現在、カスタマー API は読み取り専用です。write: スコープと read:billing はキーで選択できますが、現在、これらを使用するカスタマーエンドポイントはないため、それらを付与しても何も変わりません。実際に必要な読み取りスコープのみを付与し、書き込みエンドポイントがリリースされたときにキーを再確認してください。
キーの使用
Authorization ヘッダーでキーをベアラートークンとして送信します。
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 を返し、必要だったスコープを名前付けメッセージとして返します。すべての正常な呼び出しがキーの最後の使用タイムスタンプを更新します。
優しくポーリングしてください。これらのエンドポイントはライブアカウントデータを読み取り、それらに対するタイトループは悪用と区別できません。ダッシュボードが必要とするものの場合は1分に1回が寛容です。通常は1時間に1回で十分です。
キーのレビューと取り消し
API Keys テーブルには、各アクティブキーが Name、Prefix（キーの目に見える最初の部分）、および Scopes でリストされています。行の最後にある Revoke をクリックして削除します。
取り消しは直ちに有効になり、確認ダイアログはありません。そのキーを使用する次のリクエストは 401 で失敗します。取り消されたキーは復旧できないため、クリックする前に何がそれを使用しているか確認してください。
キーは、それを作成した人ではなく、account に属します。Team ページからチームメイトを削除しても、彼らが作成したキーは取り消されません。オフボーディングにキーレビューを組み込んでください。その人を削除してから、ここに来て彼らが作成したものを取り消します。
キーの作成と取り消しの両方は、監査ログに api_key.* アクション下で記録され、アクターと元の IP アドレスが含まれます。
リモートビルドキャッシュ
Developer ページ（設定レールの Advanced グループ内）には、Remote Build Cache があります。パネルは「マシンと CI パイプライン全体で分散キャッシュを共有することで Turborepo と Nx ビルドを加速する」方法として説明しています。
- Settings に移動して、Developer をクリックします。
- Enable remote cache をクリックします。
- 「New token generated. Copy it now, it won't be shown again」というヘッダーのパネルからトークンをコピーします。
その後、CI 設定またはローカル .env.local で2つの環境変数を設定します:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
チーム ID は Kapsule アカウント ID で、同じページのセットアップ手順に表示されています。
ページはそれ自身の互換性を述べています: Turborepo 1.x 以降、Nx 16 以降、および同じリモートキャッシュプロトコルを実装するすべてのツール。アーティファクトはアカウント単位で保存され、アカウント間で共有されることはありません。
カードにはさらに2つのコントロールがあります:
- Rotate token は新しいトークンを発行し、古いトークンを無効にします。古いトークンを保持している CI ジョブはキャッシュの使用を停止するため、トークンを回転させてシークレットを一緒に更新してください。
- Disable はキャッシュを完全にオフにします。
2つの選択
それらは関連のない問題を解決し、相互交換不可です。
API キー は、Kapsule の外部にあるものがアカウントの状態を知る必要がある場合に使用します。サイトをリストする状態ボード、ドメイン有効期限が近づいていることを警告するスクリプト、インベントリエクスポート。
リモートビルドキャッシュ は、すべてのマシンとすべての CI 実行が同じ変更されていないパッケージを再構築するためにビルドが遅い場合に使用します。これはホストされたサイトとは関係なく、アカウントデータを読み取りません。
Git からデプロイしている場合は、API を呼び出すのではなく、Kapsule Orbit を参照してください。リポジトリから直接ビルドして配送し、ビルドキャッシングはあなたのために処理されます。
トラブルシューティング
すべてのリクエストが 401 を返します。 ヘッダーを Authorization: Bearer <key> として単一のスペース付きで送信したこと、キーをコピーするときに切り詰めていないこと、および取り消されていないことを確認してください。キーの最初の部分を Prefix 列と比較して、使用しているキーが想定していることを確認してください。
リクエストがスコープを名前付けして 403 を返します。 キーにそのスコープがありません。スコープはキーが作成されるときに固定されるため、正しいスコープで置き換えを作成し、古いものを取り消してください。
API Keys カードが表示されません。 Security ページにあり、Developer ページにはありません。Developer ページはビルドキャッシュのみを保持します。
New key ボタンが何もしません。 あなたのロールが Admin 以下です。Owner または Admin に尋ねてください。
ビルドがキャッシュをヒットしていません。 TURBO_TOKEN と TURBO_TEAM の両方がビルド環境に存在することを確認し、トークンをセットしてから回転していないことを確認し、ページがまだ Active バッジを表示していることを確認します。
作成していないキーが表示されました。 侵害として扱ってください。それを取り消してから、Account Security を確認し、監査ログ で何か他が変わったかチェックしてください。