サービスアカウント、Credits 上限、長期キー、短期トークンを管理します。
このドキュメントについて
サービスアカウントは、アプリケーションや自動化処理が Qoder を使用するための組織 ID です。組織メンバーを作成せず、メンバーシートも消費しません。利用前に組織のサービスアカウント機能を有効にしてください。
共通仕様と API キーの取得を確認してください。Base URL は https://api.qoder.com です。サンプルの UUID は実在するリソースを示しません。組織内の実際の UUID に置き換えてください。
前提条件
| 操作 | Bearer 認証に使用する認証情報 |
|---|---|
| アカウントと長期キーの管理 | パスで指定した組織の組織 API キー |
| 短期トークンの発行 | パスで指定したサービスアカウント自身の有効な長期キー |
Authorization: Bearer <credential> です。短期トークンの発行には、組織 API キーや短期トークンを代用できません。
API 一覧
1. サービスアカウント作成
POST /v1/organizations/{organization_id}/service-accounts
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
organization_id | string | はい | 組織 ID |
リクエスト本文
作成には name が必須です。
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | はい | 前後の空白除去後 1~100 文字。組織内で一意 |
description | string | いいえ | 任意。前後の空白を除去し、最大 500 文字。更新時に空文字列を指定すると説明を削除 |
limitAmount | float64 | いいえ | 任意。-1 は独立した上限なし、0 は新たな Credits 消費を停止、有限の正数は上限値。作成時の既定値は -1 |
成功レスポンス(201 Created)
レスポンスフィールド
| フィールド | 型 | 説明 |
|---|---|---|
id, organizationId | string | アカウントと組織の UUID |
name | string | 組織内で一意のアカウント名 |
description | string | 任意。空の場合は省略 |
status | string | active または archived |
tokenValidAfter | string | 任意のトークン有効開始境界。UTC RFC 3339 |
createdBy | string | 作成操作を行った主体の ID |
createdAt, updatedAt | string | 作成日時、更新日時。UTC RFC 3339 |
activeKeyCount | int32 | 有効かつ期限内の長期キーの数 |
lastUsedAt | string | 最後に利用に成功した日時。未使用なら省略 |
limitAmount | float64 | 組織の現在の請求期間における Credits 上限 |
usedAmount | float64 | 同じ請求期間の Credits 使用量 |
2. サービスアカウント一覧
GET /v1/organizations/{organization_id}/service-accounts
レスポンスは serviceAccounts(アカウント配列)、maxResults(int32)、任意の nextToken を含みます。データがなければ [] を返します。最終ページにもレコードが含まれる場合があるため、配列の空判定ではなく nextToken の有無で終了を判断してください。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
organization_id | string | はい | 組織 ID |
クエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
status | string | いいえ | active または archived; 省略すると状態で絞り込みません |
keyword | string | いいえ | 名前または説明を対象とするキーワード検索。大文字・小文字を区別せず、前後の空白除去後に最大 500 文字; 既定値: なし |
maxResults | integer | いいえ | ページサイズ。最大 100; 既定値: 20 |
nextToken | string | いいえ | 前回のレスポンスに含まれるカーソル; 既定値: なし |
periodStart と periodEnd を省略すると、直近の期間が選択されます。選択できる期間がある場合、アーカイブ済みのアカウントは、その期間の使用量が 0 より大きい場合にのみ一覧に含まれます。詳しくは期間を指定したサービスアカウントの一覧取得をご覧ください。
成功レスポンス(200 OK)
3. サービスアカウント詳細取得
GET /v1/organizations/{organization_id}/service-accounts/{service_account_id}
存在しないアカウントや別組織のアカウントは 404 になります。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
organization_id | string | はい | 組織 ID |
service_account_id | string | はい | サービスアカウント ID |
成功レスポンス(200 OK)
サービスアカウントオブジェクトを返します。レスポンス例とフィールドはサービスアカウント作成を参照してください。
4. サービスアカウント更新
PUT /v1/organizations/{organization_id}/service-accounts/{service_account_id}
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
organization_id | string | はい | 組織 ID |
service_account_id | string | はい | サービスアカウント ID |
リクエスト本文
更新には name、description、limitAmount のいずれかが必要です。省略したフィールドは変更されません。
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | いいえ | 前後の空白除去後 1~100 文字。組織内で一意 |
description | string | いいえ | 任意。前後の空白を除去し、最大 500 文字。更新時に空文字列を指定すると説明を削除 |
limitAmount | float64 | いいえ | 任意。-1 は独立した上限なし、0 は新たな Credits 消費を停止、有限の正数は上限値。作成時の既定値は -1 |
成功レスポンス(200 OK)
サービスアカウントオブジェクトを返します。レスポンス例とフィールドはサービスアカウント作成を参照してください。
5. サービスアカウントのアーカイブ
POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/archive
アーカイブにリクエスト本文は不要です。状態を archived に変更し、未失効の長期キーをすべて失効させます。アーカイブ後はキーの作成・ローテーションができず、復元 API もありません。繰り返しアーカイブしても成功し、状態変更は重複しません。過去の使用量は引き続き照会できます。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
organization_id | string | はい | 組織 ID |
service_account_id | string | はい | サービスアカウント ID |
成功レスポンス(200 OK)
アーカイブ後のサービスアカウントオブジェクトを返します。status は archived、activeKeyCount は 0、tokenValidAfter はアーカイブ日時です。その他のフィールドはサービスアカウント作成を参照してください。
6. 長期キー作成
POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys
平文の token は作成またはローテーション時に一度だけ返されます。直ちにサーバー側のシークレット管理システムに保存し、URL、ログ、ソースコード、エラーメッセージに含めないでください。一覧ではマスク済みの tokenDisplay のみを返します。
既定の上限は、組織ごとに有効アカウント 100 件、アカウントごとに有効かつ期限内のキー 5 件、組織全体で有効かつ期限内のキー 500 件です。組織設定により変更される場合があります。失効済み・期限切れのキーは上限に含まれません。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
organization_id | string | はい | 組織 ID |
service_account_id | string | はい | サービスアカウント ID |
リクエスト本文
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | はい | 前後の空白除去後 1~100 文字 |
scope | string | はい | 空白区切り。空または重複した Scope は不可。最大 20 件、各 100 文字まで。利用可能な値は Qoder 導入担当に確認 |
expiresAt | string | いいえ | 現在より後の RFC 3339 日時 |
成功レスポンス(201 Created)
レスポンスフィールド
| フィールド | 型 | 説明 |
|---|---|---|
id, organizationId, serviceAccountId | string | キー、組織、アカウントの UUID |
name, scope | string | キー名と空白区切りの権限 |
tokenDisplay | string | マスク済みの値。認証には使用不可 |
status | string | active または revoked |
expiresAt | string | 任意の有効期限。未設定なら省略 |
lastUsedAt | string | 最後に利用に成功した日時。未使用なら省略 |
createdBy | string | 作成操作を行った主体の ID |
createdAt, updatedAt | string | UTC RFC 3339 日時 |
isExpired | boolean | 有効期限が切れているか |
token | string | 作成・ローテーション時のみ返却 |
status=active でも isExpired=true のキーは認証に使用できません。
7. 長期キー一覧
GET /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys
一覧には任意で status(active または revoked、既定はすべて)、maxResults(既定 20、最大 100)、nextToken を指定できます。レスポンスは keys(token を含まないキー配列)、maxResults、任意の nextToken です。空の一覧は [] になります。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
organization_id | string | はい | 組織 ID |
service_account_id | string | はい | サービスアカウント ID |
クエリパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
status | string | いいえ | active / revoked; 既定はすべて |
maxResults | integer | いいえ | 既定 20、最大 100 |
nextToken | string | いいえ | 前回のレスポンスのカーソル |
成功レスポンス(200 OK)
8. 長期キーのローテーション
POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys/{key_id}/rotate
ローテーションに本文は不要です。元の名前、Scope、有効期限を引き継ぐ新しいキーを作成し、元のキーを失効させ、新しい平文トークンを一度だけ返します。失効済み・期限切れのキーはローテーションできません。切替期間中に両方のキーを使う場合は、別のキーを作成し、呼び出し元を切り替えてから旧キーを失効させてください。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
organization_id | string | はい | 組織 ID |
service_account_id | string | はい | サービスアカウント ID |
key_id | string | はい | キー ID |
成功レスポンス(201 Created)
新しいキーオブジェクトと一度限りの平文 token を返します。レスポンス例とフィールドは長期キー作成を参照してください。
9. 長期キーの失効
DELETE /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys/{key_id}
失効に本文は不要で、204 No Content を返します。同じキーへの再実行も成功します。失効済みのキーは認証・ローテーションに使えません。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
organization_id | string | はい | 組織 ID |
service_account_id | string | はい | サービスアカウント ID |
key_id | string | はい | キー ID |
成功レスポンス(204 No Content)
204 No Content を返します。レスポンス本文はありません。
10. 短期トークン発行
POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/tokens
対象アカウント自身の長期キーで認証します。
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
organization_id | string | はい | 組織 ID |
service_account_id | string | はい | サービスアカウント ID |
リクエスト本文
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
scope | string | はい | 空でない空白区切りの値。元のキーの Scope の部分集合。全体で最大 2,048 文字、異なる Scope は最大 20 件、各 100 文字まで |
expirationSeconds | integer | いいえ | 省略または 0 の既定値は 3,600 秒。それ以外は 1~43,200 秒で、元のキーの残り有効期間を超えない |
customId | string | いいえ | 監査用の識別子。1~128 ASCII 文字。先頭は英数字、以降は英数字または ._:/@+- |
null、型の不一致は拒否されます。
成功レスポンス(200 OK)
accessToken、tokenType、expiresAt は string、expiresIn は秒単位の整数です。成功時は Cache-Control: no-store と Pragma: no-cache を返します。成功するたびに新しいトークンを発行するため、冪等ではありません。トークンの内部構造を解析せず、ログにも記録しないでください。
元のキーを失効させるかアカウントをアーカイブすると、認証情報は無効になります。ただし発行済みのトークンは、ゲートウェイの認証情報状態キャッシュが更新されるか、トークンが期限切れになるまで受け付けられる場合があります。即時失効を前提にせず、デプロイ先のキャッシュ更新間隔を確認してください。
使用例
サービスアカウント作成
サービスアカウント一覧
サービスアカウント詳細取得
サービスアカウント更新
サービスアカウントのアーカイブ
長期キー作成
長期キー一覧
長期キーのローテーション
長期キーの失効
短期トークン発行
エラーコード
エラーは requestId、code、message と、任意の details を含みます。
| HTTP | コード例 | 説明 |
|---|---|---|
400 | BadRequest, ServiceAccountLimitAmountInvalid, ServiceAccountArchived, ServiceAccountKeyScopeUnsupported, ServiceAccountKeyLimitExceeded, OrganizationServiceAccountKeyLimitExceeded | フィールド、状態、Scope、設定上限の問題 |
401 | Unauthorized | 認証情報の欠落、無効、期限切れ |
403 | Forbidden, OrganizationPlanCapabilityForbidden | 主体、組織、Scope が不適切、または機能が未有効 |
404 | NotFound | 対象が存在しない、または別組織に所属 |
409 | ServiceAccountNameAlreadyExists, ServiceAccountKeyAlreadyExists | アカウント名またはキーの競合 |
500 | InternalError | 内部エラー |
503 | InternalError または依存サービス固有のコード | トークン発行サービスまたは依存サービスが利用不可 |
code を処理し、すべての入力エラーを BadRequest、すべての競合を AlreadyExists と想定しないでください。
履歴イベントと Credits 純使用量は使用量 APIで取得できます。