Kapsule Orbit API トークンと REST API

APIトークンを使用すると、スクリプト、CIパイプライン、またはあなた自身のツーリングがブラウザセッションなしでOrbitを動かすことができます。デプロイメントのトリガー、CIチェック結果のレポート、ビルドアーティファクトのダウンロード、cronジョブの管理など、あなた自身がスコープを設定したBearerトークンで認証されたすべてが可能です。

トークンの場所

Orbitを開き、トップレベルナビゲーションからTokensを選択します。ページのタイトルはAPI Access Tokensで、その冒頭のルールを明記しています。トークンは作成時に1回だけ表示されます。

完全なエンドポイントドキュメントはワンクリックで表示されます。API ReferenceカードにはView docsボタンがあり、すべてのOrbitエンドポイント用のパネル内リファレンスが開きます。

トークンの作成

1. New tokenをクリックします。
2. Token nameを付けます。使用するもの（例えばCIワークフロー）に基づいて名前を付けると、後で在庫が読みやすくなります。
3. Scopesを選択します。
4. オプションでExpiryを設定します。トークンが期限切れにならないようにする場合は、空白のままにしておきます。
5. Create tokenをクリックします。

生のトークンは一度だけ、One-time revealという見出しの下に、コピーボタン付きで表示されます。すぐにあなたのCIシークレットストアに貼り付けてください。再度表示する方法はありません。トークンのSHA-256ハッシュだけが保存されているため、Kapsule自体でも回復することができません。

1つのアカウントは最大20個のアクティブなトークンを保持できます。21番目を作成しようとすると、最初に既存のものを無効化するよう指示するメッセージで拒否されます。

スコープ

スコープはトークンの全要点です。各トークンは、あなたが与えたパーミッションのみを持ちます。

新しいトークンはデフォルトでdeploy:writeとproject:readになります。これはデプロイメントパイプラインに必要なもので、それ以上は必要ありません。

仕事に必要な最小限のセットを付与します。CIの結果をレポートするだけで良いトークンにはproject:writeは必要ありません。読み取り専用の監視スクリプトには書き込みスコープは必要ありません。リファレンス内の各エンドポイントには、必要な最小限のスコープが記載されています。

トークンの使用

認証は、APIベースhttps://kapsulehost.comに対するBearerヘッダーです:

curl -X POST https://kapsulehost.com/api/orbit/$ORBIT_PROJECT_ID/deployments \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

「Tokens」ページには、準備完了なCI/CD usageスニペットとGitHub Actions starterワークフローが含まれています。スターターは.github/workflows/orbit-deploy.ymlとして保存され、2つのリポジトリシークレットORBIT_TOKENとORBIT_PROJECT_IDが必要です。ページからコピーするのではなく、転記してください。

APIがカバーする範囲

パネル内リファレンスでは、各領域をパラメータと必要なスコープ付きで文書化しています:

• Deployments: デプロイメントをトリガーします。オプションで指定されたブランチ上で、またはオプションで5分から30日先の将来の時間をスケジュールして、最大500文字の注記付きで。リストは、コミット、メッセージ、ブランチ、著者全体のあいまい検索をサポートし、ブランチ、ステータス、環境でのフィルタリング、および1ページあたり最大100個の結果を含むカーソルページネーションをサポートします。
• Deployment checks: CIジョブの開始時に品質ゲートを登録してから、終了時に結果をレポートします。失敗したrequiredチェックはデプロイメントをFAILEDに移動し、環境を以前の成功したデプロイメントに戻します。これはあなた自身のテストスイートを真のデプロイゲートにする方法です。
• Branch protection: 必要なチェックが合格し、オプションで誰かが承認するまで、自動デプロイメントをブロックするグロブパターンルール。プロジェクトあたり最大10ルール。
• Build artifacts: 成功したデプロイメントの実行可能な出力に対して、事前署名されたダウンロードURLを取得します。URLは15分間有効です。
• Project transfer: 別のアカウントへの転送を開始、キャンセル、ステータスを確認します。Transferring an Orbit Projectを参照してください。
• Cron jobs: リスト、作成、更新、削除、トリガー、実行履歴の読み取りを行います。Orbit Cron Jobsを参照してください。
• Timeline annotations: インシデント、リリース、マイルストーン、ノート、フラグの注釈を作成して管理します。Orbit Timeline Annotationsを参照してください。
• Status page: パブリックステータスページの設定を読み取りおよび書き込みします。Orbit Status Pageを参照してください。
• Edge functions: エッジハンドラーをリスト、作成、更新、デプロイします。Orbit Edge Functionsを参照してください。

パネルからのセッション認証はBearerトークンと並行して機能するため、ブラウザから呼び出せるエンドポイントは通常、スクリプトからも呼び出せます。

Turbo Remote Cache

「Tokens」ページにはRemote Build Cacheカードもあります。これはTurborepo Remote Cache Protocolを実装し、モノレポがCI実行と開発者マシン間でビルドキャッシュを共有できるようにします。

カード上で有効にし、生成されたトークンをコピーして、あなたのアカウントIDと共にTURBO_TEAMとして設定します。最大150 MBのアーティファクトが受け入れられます。カードはRotate tokenとDisableも提供しています。

モノレポのCIが変更されていないパッケージの再構築に大部分の時間を費やす場合、これはこのページで最も価値のある単一のものです。

在庫の管理

Token inventoryには、すべてのアクティブなトークンが以下の情報とともに表示されます:

• Created時刻。
• Last used時刻、またはNever。
• Expires時刻。期限切れになるとexpiredバッジが表示されます。

監査する対象はLast used列です。使用されたことがないトークンは、設定が間違っているか忘れられているかのいずれかで、どちらにしても何も実行していない認証情報が存在しています。ページ自体のヒントは明確に言っています。認識できないものすべてを無効化します。

トークンの無効化

その行の無効化コントロールをクリックします。確認は明確です。そのトークンで認証しているすべてのものは即座にアクセスを失い、これは元に戻すことができません。

パイプラインが廃止されるとき、CIシークレットへのアクセス権を持つ誰かが去るとき、またはトークンが漏洩した可能性があると少しでも疑った場合に無効化します。部分的な無効化と猶予期間はなく、これは漏洩の場合はまさにあなたが求めているものです。

トラブルシューティング

401 Unauthorized。 ヘッダーが間違っているか、トークンが無効化または有効期限が切れています。ヘッダーがAuthorization: Bearer <token>で単一スペースであること、およびCIシークレットに末尾の改行がないことを確認してください。

403 Forbidden。 トークンは有効ですが、そのエンドポイントのスコープが不足しています。リファレンスにはエンドポイントあたりの最小限のスコープが記載されています。スコープは作成時に固定されているため、正しいセットで新しいトークンを作成してください。

作成時に429。 20トークンの制限に達しています。在庫から何かを無効化します。

アーティファクトURLが機能を停止する。 事前署名されたURLは15分続きます。URLを保存するのではなく、新しいものをリクエストしてください。

スケジュール済みデプロイメントが拒否される。 スケジュール済み時刻は、5分から30日先の将来にある必要があります。

次のステップ

• Deploying Your Project: トリガーされたデプロイメントが実際に実行する操作。
• Orbit Deployment Pipeline: APIデプロイメントが満たすゲートを確認。
• Orbit Plan Limits: プランに含まれるもの。