Skip to main content
OpenAPI

サービスアカウント API

サービスアカウント、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_idstringはい組織 ID

リクエスト本文

作成には name が必須です。
{
  "name": "CI Automation",
  "description": "本番 CI ジョブ",
  "limitAmount": 1000
}
パラメータ型必須説明
namestringはい前後の空白除去後 1~100 文字。組織内で一意
descriptionstringいいえ任意。前後の空白を除去し、最大 500 文字。更新時に空文字列を指定すると説明を削除
limitAmountfloat64いいえ任意。-1 は独立した上限なし、0 は新たな Credits 消費を停止、有限の正数は上限値。作成時の既定値は -1

成功レスポンス(201 Created)

{
  "id": "019c1234-5678-7abc-8def-012345678901",
  "organizationId": "019c1234-5678-7abc-8def-012345678900",
  "name": "CI Automation",
  "description": "本番 CI ジョブ",
  "status": "active",
  "createdBy": "019c1234-5678-7abc-8def-012345678904",
  "createdAt": "2026-07-20T09:00:00Z",
  "updatedAt": "2026-07-20T09:00:00Z",
  "activeKeyCount": 0,
  "limitAmount": 1000,
  "usedAmount": 0
}

レスポンスフィールド

フィールド型説明
id, organizationIdstringアカウントと組織の UUID
namestring組織内で一意のアカウント名
descriptionstring任意。空の場合は省略
statusstringactive または archived
tokenValidAfterstring任意のトークン有効開始境界。UTC RFC 3339
createdBystring作成操作を行った主体の ID
createdAt, updatedAtstring作成日時、更新日時。UTC RFC 3339
activeKeyCountint32有効かつ期限内の長期キーの数
lastUsedAtstring最後に利用に成功した日時。未使用なら省略
limitAmountfloat64組織の現在の請求期間における Credits 上限
usedAmountfloat64同じ請求期間の Credits 使用量

2. サービスアカウント一覧

GET /v1/organizations/{organization_id}/service-accounts レスポンスは serviceAccounts(アカウント配列)、maxResults(int32)、任意の nextToken を含みます。データがなければ [] を返します。最終ページにもレコードが含まれる場合があるため、配列の空判定ではなく nextToken の有無で終了を判断してください。

パスパラメータ

パラメータ型必須説明
organization_idstringはい組織 ID

クエリパラメータ

パラメータ型必須説明
statusstringいいえactive または archived; 省略すると状態で絞り込みません
keywordstringいいえ名前または説明を対象とするキーワード検索。大文字・小文字を区別せず、前後の空白除去後に最大 500 文字; 既定値: なし
maxResultsintegerいいえページサイズ。最大 100; 既定値: 20
nextTokenstringいいえ前回のレスポンスに含まれるカーソル; 既定値: なし
periodStart と periodEnd を省略すると、直近の期間が選択されます。選択できる期間がある場合、アーカイブ済みのアカウントは、その期間の使用量が 0 より大きい場合にのみ一覧に含まれます。詳しくは期間を指定したサービスアカウントの一覧取得をご覧ください。

成功レスポンス(200 OK)

{
  "serviceAccounts": [
    {
      "id": "019c1234-5678-7abc-8def-012345678901",
      "organizationId": "019c1234-5678-7abc-8def-012345678900",
      "name": "CI Automation",
      "description": "本番 CI ジョブ",
      "status": "active",
      "createdBy": "019c1234-5678-7abc-8def-012345678904",
      "createdAt": "2026-07-20T09:00:00Z",
      "updatedAt": "2026-07-20T09:00:00Z",
      "activeKeyCount": 1,
      "lastUsedAt": "2026-07-20T09:30:00Z",
      "limitAmount": 1000,
      "usedAmount": 125.5
    }
  ],
  "maxResults": 20
}

3. サービスアカウント詳細取得

GET /v1/organizations/{organization_id}/service-accounts/{service_account_id} 存在しないアカウントや別組織のアカウントは 404 になります。

パスパラメータ

パラメータ型必須説明
organization_idstringはい組織 ID
service_account_idstringはいサービスアカウント ID

成功レスポンス(200 OK)

サービスアカウントオブジェクトを返します。レスポンス例とフィールドはサービスアカウント作成を参照してください。

4. サービスアカウント更新

PUT /v1/organizations/{organization_id}/service-accounts/{service_account_id}

パスパラメータ

パラメータ型必須説明
organization_idstringはい組織 ID
service_account_idstringはいサービスアカウント ID

リクエスト本文

更新には name、description、limitAmount のいずれかが必要です。省略したフィールドは変更されません。
{
  "name": "CI Production",
  "description": "",
  "limitAmount": 1500
}
パラメータ型必須説明
namestringいいえ前後の空白除去後 1~100 文字。組織内で一意
descriptionstringいいえ任意。前後の空白を除去し、最大 500 文字。更新時に空文字列を指定すると説明を削除
limitAmountfloat64いいえ任意。-1 は独立した上限なし、0 は新たな Credits 消費を停止、有限の正数は上限値。作成時の既定値は -1

成功レスポンス(200 OK)

サービスアカウントオブジェクトを返します。レスポンス例とフィールドはサービスアカウント作成を参照してください。

5. サービスアカウントのアーカイブ

POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/archive アーカイブにリクエスト本文は不要です。状態を archived に変更し、未失効の長期キーをすべて失効させます。アーカイブ後はキーの作成・ローテーションができず、復元 API もありません。繰り返しアーカイブしても成功し、状態変更は重複しません。過去の使用量は引き続き照会できます。

パスパラメータ

パラメータ型必須説明
organization_idstringはい組織 ID
service_account_idstringはいサービスアカウント 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_idstringはい組織 ID
service_account_idstringはいサービスアカウント ID

リクエスト本文

{
  "name": "CI Production",
  "scope": "<space-separated-scopes>",
  "expiresAt": "2027-07-20T00:00:00Z"
}
パラメータ型必須説明
namestringはい前後の空白除去後 1~100 文字
scopestringはい空白区切り。空または重複した Scope は不可。最大 20 件、各 100 文字まで。利用可能な値は Qoder 導入担当に確認
expiresAtstringいいえ現在より後の RFC 3339 日時

成功レスポンス(201 Created)

{
  "id": "019c1234-5678-7abc-8def-012345678902",
  "organizationId": "019c1234-5678-7abc-8def-012345678900",
  "serviceAccountId": "019c1234-5678-7abc-8def-012345678901",
  "name": "CI Production",
  "tokenDisplay": "<masked_service_account_key>",
  "scope": "<space-separated-scopes>",
  "status": "active",
  "expiresAt": "2027-07-20T00:00:00Z",
  "createdBy": "019c1234-5678-7abc-8def-012345678904",
  "createdAt": "2026-07-20T09:00:00Z",
  "updatedAt": "2026-07-20T09:00:00Z",
  "isExpired": false,
  "token": "<service_account_key>"
}

レスポンスフィールド

フィールド型説明
id, organizationId, serviceAccountIdstringキー、組織、アカウントの UUID
name, scopestringキー名と空白区切りの権限
tokenDisplaystringマスク済みの値。認証には使用不可
statusstringactive または revoked
expiresAtstring任意の有効期限。未設定なら省略
lastUsedAtstring最後に利用に成功した日時。未使用なら省略
createdBystring作成操作を行った主体の ID
createdAt, updatedAtstringUTC RFC 3339 日時
isExpiredboolean有効期限が切れているか
tokenstring作成・ローテーション時のみ返却
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_idstringはい組織 ID
service_account_idstringはいサービスアカウント ID

クエリパラメータ

パラメータ型必須説明
statusstringいいえactive / revoked; 既定はすべて
maxResultsintegerいいえ既定 20、最大 100
nextTokenstringいいえ前回のレスポンスのカーソル

成功レスポンス(200 OK)

{
  "keys": [
    {
      "id": "019c1234-5678-7abc-8def-012345678902",
      "organizationId": "019c1234-5678-7abc-8def-012345678900",
      "serviceAccountId": "019c1234-5678-7abc-8def-012345678901",
      "name": "CI Production",
      "tokenDisplay": "<masked_service_account_key>",
      "scope": "<space-separated-scopes>",
      "status": "active",
      "expiresAt": "2027-07-20T00:00:00Z",
      "createdBy": "019c1234-5678-7abc-8def-012345678904",
      "createdAt": "2026-07-20T09:00:00Z",
      "updatedAt": "2026-07-20T09:00:00Z",
      "isExpired": false
    }
  ],
  "maxResults": 20
}

8. 長期キーのローテーション

POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys/{key_id}/rotate ローテーションに本文は不要です。元の名前、Scope、有効期限を引き継ぐ新しいキーを作成し、元のキーを失効させ、新しい平文トークンを一度だけ返します。失効済み・期限切れのキーはローテーションできません。切替期間中に両方のキーを使う場合は、別のキーを作成し、呼び出し元を切り替えてから旧キーを失効させてください。

パスパラメータ

パラメータ型必須説明
organization_idstringはい組織 ID
service_account_idstringはいサービスアカウント ID
key_idstringはいキー ID

成功レスポンス(201 Created)

新しいキーオブジェクトと一度限りの平文 token を返します。レスポンス例とフィールドは長期キー作成を参照してください。

9. 長期キーの失効

DELETE /v1/organizations/{organization_id}/service-accounts/{service_account_id}/keys/{key_id} 失効に本文は不要で、204 No Content を返します。同じキーへの再実行も成功します。失効済みのキーは認証・ローテーションに使えません。

パスパラメータ

パラメータ型必須説明
organization_idstringはい組織 ID
service_account_idstringはいサービスアカウント ID
key_idstringはいキー ID

成功レスポンス(204 No Content)

204 No Content を返します。レスポンス本文はありません。

10. 短期トークン発行

POST /v1/organizations/{organization_id}/service-accounts/{service_account_id}/tokens 対象アカウント自身の長期キーで認証します。

パスパラメータ

パラメータ型必須説明
organization_idstringはい組織 ID
service_account_idstringはいサービスアカウント ID

リクエスト本文

{
  "scope": "<space-separated-scopes>",
  "expirationSeconds": 3600,
  "customId": "deployment-2026-07-20"
}
パラメータ型必須説明
scopestringはい空でない空白区切りの値。元のキーの Scope の部分集合。全体で最大 2,048 文字、異なる Scope は最大 20 件、各 100 文字まで
expirationSecondsintegerいいえ省略または 0 の既定値は 3,600 秒。それ以外は 1~43,200 秒で、元のキーの残り有効期間を超えない
customIdstringいいえ監査用の識別子。1~128 ASCII 文字。先頭は英数字、以降は英数字または ._:/@+-
受け付けるフィールドはこの 3 つだけです。未知のフィールド、明示的な null、型の不一致は拒否されます。

成功レスポンス(200 OK)

{
  "accessToken": "<opaque_service_account_token>",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "expiresAt": "2026-07-20T10:00:00Z"
}
accessToken、tokenType、expiresAt は string、expiresIn は秒単位の整数です。成功時は Cache-Control: no-store と Pragma: no-cache を返します。成功するたびに新しいトークンを発行するため、冪等ではありません。トークンの内部構造を解析せず、ログにも記録しないでください。 元のキーを失効させるかアカウントをアーカイブすると、認証情報は無効になります。ただし発行済みのトークンは、ゲートウェイの認証情報状態キャッシュが更新されるか、トークンが期限切れになるまで受け付けられる場合があります。即時失効を前提にせず、デプロイ先のキャッシュ更新間隔を確認してください。

使用例

サービスアカウント作成

curl -X POST "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts" \
  -H "Authorization: Bearer <organization_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI Automation","description":"本番 CI ジョブ","limitAmount":1000}'

サービスアカウント一覧

curl -X GET "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts?maxResults=20" \
  -H "Authorization: Bearer <organization_api_key>"

サービスアカウント詳細取得

curl -X GET "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901" \
  -H "Authorization: Bearer <organization_api_key>"

サービスアカウント更新

curl -X PUT "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901" \
  -H "Authorization: Bearer <organization_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI Production","description":"","limitAmount":1500}'

サービスアカウントのアーカイブ

curl -X POST "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/archive" \
  -H "Authorization: Bearer <organization_api_key>"

長期キー作成

curl -X POST "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/keys" \
  -H "Authorization: Bearer <organization_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI Production","scope":"<space-separated-scopes>","expiresAt":"2027-07-20T00:00:00Z"}'

長期キー一覧

curl -X GET "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/keys?maxResults=20" \
  -H "Authorization: Bearer <organization_api_key>"

長期キーのローテーション

curl -X POST "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/keys/019c1234-5678-7abc-8def-012345678902/rotate" \
  -H "Authorization: Bearer <organization_api_key>"

長期キーの失効

curl -X DELETE "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/keys/019c1234-5678-7abc-8def-012345678902" \
  -H "Authorization: Bearer <organization_api_key>"

短期トークン発行

curl -X POST "https://api.qoder.com/v1/organizations/019c1234-5678-7abc-8def-012345678900/service-accounts/019c1234-5678-7abc-8def-012345678901/tokens" \
  -H "Authorization: Bearer <service_account_key>" \
  -H "Content-Type: application/json" \
  -d '{"scope":"<space-separated-scopes>","expirationSeconds":3600,"customId":"deployment-2026-07-20"}'

エラーコード

エラーは requestId、code、message と、任意の details を含みます。
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "name is required"
}
HTTPコード例説明
400BadRequest, ServiceAccountLimitAmountInvalid, ServiceAccountArchived, ServiceAccountKeyScopeUnsupported, ServiceAccountKeyLimitExceeded, OrganizationServiceAccountKeyLimitExceededフィールド、状態、Scope、設定上限の問題
401Unauthorized認証情報の欠落、無効、期限切れ
403Forbidden, OrganizationPlanCapabilityForbidden主体、組織、Scope が不適切、または機能が未有効
404NotFound対象が存在しない、または別組織に所属
409ServiceAccountNameAlreadyExists, ServiceAccountKeyAlreadyExistsアカウント名またはキーの競合
500InternalError内部エラー
503InternalError または依存サービス固有のコードトークン発行サービスまたは依存サービスが利用不可
業務固有のエラーコードは保持されます。HTTP ステータスと実際の code を処理し、すべての入力エラーを BadRequest、すべての競合を AlreadyExists と想定しないでください。 履歴イベントと Credits 純使用量は使用量 APIで取得できます。