KapsuleHostはあなたに2つの開発者向けサーフェスを提供しています。アカウントをプログラムで読み取るためのスコープ付きAPIキーと、あなた自身のマシンとCIランナー上でTurborepoとNxビルドを高速化するリモートビルドキャッシュです。
どちらもデフォルトでは有効になっていません。どちらも設定から作成され、どちらもシークレットを正確に1回だけ提供します。
APIキーの作成
APIキーは設定の下のセキュリティに存在し、APIキーカード内にあります。
- 設定に移動し、セキュリティをクリックします。
- APIキーまでスクロールして、新しいキーをクリックします。
- キーに名前を付けます。フィールドは「キー名（例：マイオートメーションスクリプト）」と提案しています。名前はあなた用ですので、キーがどこで使用されるかを示すようにしてください。
- スコープチップをクリックして、キーが何をできるかを選択します。3つの読み取りスコープがあらかじめ選択されています：
read:sites、read:email、およびread:domains。チップをクリックして追加または削除します。 - 作成をクリックします。
完全なキーは1回だけ表示されます。「今すぐコピー」という見出しの付いた緑色のパネルに表示されます。シークレットストアに直接コピーしてください。そのパネルを閉じると、キーは消えます。短いプレフィックスのみが保持され、それがリストが今後表示できるすべてです。
キーは2回目以降に表示されることはなく、復元することもできません。失った場合は、そのキーを失効させ、新しいキーを作成してください。共有ドキュメント、チケット、コミット、またはチャットメッセージに貼り付けないでください。
オーナーおよび管理者ロールのみがキーを作成できます。他のロールを持つユーザーはパーミッションエラーを取得します。キーが作成されるとき、セキュリティアラートメールがそれを作成した人のアドレスに送信されるため、予期しないメールが届いた場合は即座に調査する価値があります。
スコープ
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キーテーブルは各アクティブキーを名前、プレフィックス（キーの見える始まり）、およびスコープでリストします。行の最後の失効をクリックしてそれを無効化します。
失効は直ちに有効になり、確認ダイアログはありません。そのキーを使用する次のリクエストは401で失敗します。失効したキーは復元できないため、クリックする前にそれを使用しているものを確認してください。
キーはアカウントに属し、それらを作成した人には属しません。チームページからチームメートを削除しても、彼らが作成したキーは失効しません。オフボーディングにキーレビューを組み込んでください：その人を削除してから、ここに来て、彼らが作成したものを失効させます。
キー作成と失効の両方は、監査ログのapi_key.*アクション下に記録され、アクターと発信元IPアドレスが記載されます。
リモートビルドキャッシュ
設定レールの詳細グループの開発者ページは、リモートビルドキャッシュを提供しています。パネルはそれを「マシンとCIパイプライン全体で分散キャッシュを共有することでTurborepoとNxビルドを高速化する方法」として説明しています。
- 設定に移動し、開発者をクリックします。
- リモートキャッシュを有効にするをクリックします。
- 「新しいトークンが生成されました。今すぐコピーしてください。二度と表示されません」というタイトルのパネルからトークンをコピーします。
その後、CI設定またはローカル.env.localに2つの環境変数を設定します：
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の両方がビルド環境に存在すること、設定してからトークンが回転されていないこと、ページがまだアクティブバッジを表示していることを確認してください。
私が作成していないキーが表示されました。 それを侵害として扱います。それを失効させてから、アカウントセキュリティを確認し、監査ログで他に何が変更されたかを確認します。