Personal Access Token（PAT）または Service Account Token（SAT）を使用して Qoder Cloud Agents API リクエストを認証します。
Qoder Cloud Agents API では、**Personal Access Token（PAT）**と **Service Account Token（SAT）**の 2 種類の Bearer Token を使用できます。すべての API リクエストで、
SAT の交換と業務 API のリクエストでは、同じリージョンのエンドポイントを使用する必要があります。以下のサービスエンドポイントを設定します。
Service Token Exchange API を呼び出して、SA Key を SAT に交換します。
レスポンスの
同じ SAT を使用して Forward（
同じ SAT で両方の API を呼び出せます。
PAT または SAT を Bearer Token として Cloud Agents API に渡します。
選択した Token を共通の環境変数に設定します。
完全なリクエスト例：
Authorization ヘッダーに有効な Token を 1 つ指定する必要があります。
| Token | 用途 | 取得方法 |
|---|---|---|
| PAT | ユーザー ID。個人での開発やテストに適しています | Qoder コンソールで作成 |
| SAT | Service Account ID。サーバー側の連携や自動化に適しています | Service Account API Key（SA Key）を短期 JWT に交換 |
SA Key は、SAT との交換に使用する長期認証情報です。Cloud Agents の業務 API を SA Key で直接呼び出さないでください。
サービスリージョンを選択する
SAT の交換と業務 API のリクエストでは、同じリージョンのエンドポイントを使用する必要があります。以下のサービスエンドポイントを設定します。
オプション 1：PAT を使用する
PAT の取得
- Qoder コンソールにサインインします。
- 設定 → Personal Access Tokens を開きます。
- Token の作成をクリックし、名前、スコープ、有効期限を設定します。
- PAT をコピーし、環境変数に設定します。
PAT には
pt- プレフィックスが付き、完全な値は作成時に一度だけ表示されます。ソース管理にコミットしたり、共有したりしないでください。オプション 2：Service Account と SAT を使用する
SA Key の取得と設定
- 組織管理者として Qoder コンソールにサインインします。
- 組織管理で Service Account を作成または選択します。
- Service Account の詳細ページで API Key を作成します。作成時にスコープを選択する必要はありません。必要なスコープは、後で SAT に交換するときに指定します。
- SA Key をコピーし、環境変数に設定します。
完全な SA Key は作成時に一度だけ表示されます。シークレットマネージャーで保管し、ソースコードやログには記録しないでください。
SA Key を SAT（JWT）に交換する
Service Token Exchange API を呼び出して、SA Key を SAT に交換します。
| フィールド | 説明 |
|---|---|
grant_type | client_credentials を指定します |
audience | qoder を指定します |
scope | 交換リクエストで指定します。Managed API のみの場合は qca.access、Forward API と Managed API の両方の場合は qca.access forward.access を使用します。SA Key に設定された権限を超えるスコープは指定できません |
ttl_seconds | SAT の有効期間（秒）。最大値は 43200（12 時間）です |
access_token が SAT です。期限切れの SAT は更新できません。SA Key で交換 API を再度呼び出してください。
同じ SAT で Forward API と Managed API を呼び出す
同じ SAT を使用して Forward（/api/v1/forward/*）と Managed（/api/v1/cloud/*）の両方の API を呼び出す必要があるサーバー側連携では、交換時に qca.access と forward.access の両方をリクエストします。
既存の連携との互換性
- Managed API のみを呼び出す既存の連携では、引き続き
qca.accessのみをリクエストして使用できます。 - PAT の取得方法と使用方法は変更されません。
- Forward API のみを呼び出す場合、明示的な失効が必要な場合、または単一の Identity に関連付けられた SATが必要な場合は、引き続き Forward の Token API を使用できます。
Bearer ヘッダー形式
PAT または SAT を Bearer Token として Cloud Agents API に渡します。
セキュリティに関する推奨事項
- 開発、ステージング、本番環境ごとに個別の PAT または SA Key を使用してください。
- PAT と SA Key はハードコードせず、シークレットマネージャーに保存してください。
- SAT に交換するときは、連携に必要な最小限のスコープのみをリクエストしてください。
- 現在の SAT が期限切れになる前に新しい SAT と交換し、稼働中のサービスで安全にローテーションしてください。
- PAT または SA Key が漏えいした場合は、コンソールですぐに失効またはローテーションしてください。