正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

サービスアカウントAPI

  • プラン: Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このAPIを使用して、サービスアカウントを操作します。

ユーザーAPIを介してサービスアカウントを操作することもできます。

インスタンスサービスアカウント

  • 提供形態: GitLab Self-Managed、GitLab Dedicated

インスタンスサービスアカウントは、GitLabインスタンス全体で利用できますが、ヒューマンユーザーと同様に、グループやプロジェクトに追加する必要があります。

インスタンスサービスアカウントのパーソナルアクセストークンを管理するには、パーソナルアクセストークンAPIを使用します。

前提要件:

  • インスタンスへの管理者アクセス権が必要です。

すべてのインスタンスサービスアカウントをリスト表示

すべてのインスタンスサービスアカウントをリスト表示します。

結果をフィルタリングするには、pageおよびper_page ページネーションパラメータを使用します。

GET /service_accounts

サポートされている属性は以下のとおりです:

属性型必須説明
order_by文字列いいえ結果を並べ替える属性。使用可能な値: idまたはusername。デフォルト値: id。
sort文字列いいえ結果をソートする方向。使用可能な値: descまたはasc。デフォルト値: desc。

リクエスト例:

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/service_accounts"

レスポンス例:

[
  {
    "id": 114,
    "username": "service_account_33",
    "name": "Service account user"
  },
  {
    "id": 137,
    "username": "service_account_34",
    "name": "john doe"
  }
]

インスタンスサービスアカウントを作成

インスタンスサービスアカウントを作成します。

POST /service_accounts
POST /service_accounts?email=custom_email@gitlab.example.com

サポートされている属性は以下のとおりです:

属性型必須説明
name文字列いいえユーザー名。設定されていない場合は、Service account userを使用します。
username文字列いいえユーザーアカウントのユーザー名。未定義の場合、service_account_が前に付いた名前が生成されます。
email文字列いいえユーザーアカウントのメール。未定義の場合、応答不要のメールアドレスが生成されます。メール確認設定がオフになっていない限り、カスタムメールアドレスには確認が必要です。

リクエスト例:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/service_accounts"

レスポンス例:

{
  "id": 57,
  "username": "service_account_6018816a18e515214e0c34c2b33523fc",
  "name": "Service account user",
  "email": "service_account_6018816a18e515214e0c34c2b33523fc@noreply.gitlab.example.com"
}

email属性で定義されたメールアドレスが別のユーザーによって既に使用されている場合、400 Bad requestエラーが返されます。

インスタンスサービスアカウントを更新

指定されたインスタンスサービスアカウントを更新します。

PATCH /service_accounts/:id

パラメータは以下のとおりです:

属性型必須説明
id整数はいサービスアカウントのID。
name文字列いいえユーザー名。
username文字列いいえユーザーアカウントのユーザー名。
email文字列いいえユーザーアカウントのメール。メール確認設定がオフになっていない限り、カスタムメールアドレスには確認が必要です。

リクエスト例:

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/service_accounts/57" --data "name=Updated Service Account email=updated_email@example.com"

レスポンス例:

{
  "id": 57,
  "username": "service_account_6018816a18e515214e0c34c2b33523fc",
  "name": "Updated Service Account",
  "email": "service_account_<random_hash>@noreply.gitlab.example.com",
  "unconfirmed_email": "custom_email@example.com"
}

グループのサービスアカウント

グループサービスアカウントは特定のトップレベルグループが所有しており、ヒューマンユーザーと同様にサブグループおよびプロジェクトへのメンバーシップを継承できます。

前提要件:

  • GitLab.comの場合、グループのオーナーロールが必要です。
  • GitLab Self-ManagedまたはGitLab Dedicatedでは、次の条件を満たす必要があります:

すべてのグループサービスアカウントをリスト表示

指定されたトップレベルグループ内のすべてのサービスアカウントをリスト表示します。

結果をフィルタリングするには、pageおよびper_page ページネーションパラメータを使用します。

GET /groups/:id/service_accounts

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいターゲットグループのIDまたはURLエンコードされたパス。
order_by文字列いいえusernameまたはidでユーザーのリストを注文します。デフォルトはidです。
sort文字列いいえascまたはdescでのソートを指定します。デフォルトはdescです。

リクエスト例:

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts"

レスポンス例:

[

  {
    "id": 57,
    "username": "service_account_group_345_<random_hash>",
    "name": "Service account user",
    "email": "service_account_group_345_<random_hash>@noreply.gitlab.example.com"
  },
  {
    "id": 58,
    "username": "service_account_group_346_<random_hash>",
    "name": "Service account user",
    "email": "service_account_group_346_<random_hash>@noreply.gitlab.example.com",
    "unconfirmed_email": "custom_email@example.com"
  }
]

グループサービスアカウントを作成

指定されたトップレベルグループにサービスアカウントを作成します。

このエンドポイントは、トップレベルグループでのみ機能します。

POST /groups/:id/service_accounts

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいトップレベルグループのIDまたはURLエンコードされたパス。
name文字列いいえユーザーアカウント名。指定されていない場合は、Service account userを使用します。
username文字列いいえユーザーアカウントのユーザー名。指定しない場合、service_account_group_が前に付加された名前が生成されます。
email文字列いいえユーザーアカウントのメール。指定しない場合、service_account_group_が前に付加されたメールが生成されます。グループに一致する確認済みのドメインがない限り、またはメール確認設定がオフになっていない限り、カスタムメールアドレスには確認が必要です。

リクエスト例:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts" --data "email=custom_email@example.com"

レスポンス例:

{
  "id": 57,
  "username": "service_account_group_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Service account user",
  "email": "custom_email@example.com"
}

グループサービスアカウントを更新

指定されたトップレベルグループ内のサービスアカウントを更新します。

このエンドポイントは、トップレベルグループでのみ機能します。

PATCH /groups/:id/service_accounts/:user_id

パラメータ:

属性型必須説明
id整数または文字列はいターゲットグループのIDまたはURLエンコードされたパス。
user_id整数はいサービスアカウントのID。
name文字列いいえユーザーの名前。
username文字列いいえユーザーのユーザー名。
email文字列いいえユーザーアカウントのメール。検証済みのドメインがグループに一致するか、メール確認設定がオフになっている場合を除き、カスタムメールアドレスには確認が必要です。

リクエスト例:

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts/57" --data "name=Updated Service Account email=updated_email@example.com"

レスポンス例:

{
  "id": 57,
  "username": "service_account_group_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Updated Service Account",
  "email": "service_account_group_345_<random_hash>@noreply.gitlab.example.com",
  "unconfirmed_email": "custom_email@example.com"
}

グループサービスアカウントを削除

指定されたトップレベルグループからサービスアカウントを削除します。

このエンドポイントは、トップレベルグループでのみ機能します。

DELETE /groups/:id/service_accounts/:user_id

パラメータ:

属性型必須説明
id整数または文字列はいターゲットグループのIDまたはURLエンコードされたパス。
user_id整数はいサービスアカウントのID。
hard_deleteブール値いいえtrueの場合、通常はGhostユーザーに移動されるコントリビュートは、代わりに削除されます。また、このサービスアカウントのみが所有するグループも削除されます。

リクエスト例:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts/181"

グループサービスアカウントのすべてのパーソナルアクセストークンをリスト表示

トップレベルグループ内のサービスアカウントのすべてのパーソナルアクセストークンをリストします。

GET /groups/:id/service_accounts/:user_id/personal_access_tokens

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいトップレベルグループのIDまたはURLエンコードされたパス。
user_id整数はいサービスアカウントのID。
created_after日時（ISO 8601）いいえ定義されている場合、指定された時刻より後に作成されたトークンを返します。
created_before日時（ISO 8601）いいえ定義されている場合、指定された時刻より前に作成されたトークンを返します。
expires_after日付（ISO 8601）いいえ定義されている場合、指定された時刻より後に有効期限が切れるトークンを返します。
expires_before日付（ISO 8601）いいえ定義されている場合、指定された時刻より前に有効期限が切れるトークンを返します。
last_used_after日時（ISO 8601）いいえ定義されている場合、指定された時刻より後に最終使用されたトークンを返します。
last_used_before日時（ISO 8601）いいえ定義されている場合、指定された時刻より前に最終使用されたトークンを返します。
revokedブール値いいえtrueの場合、失効したトークンのみを返します。
search文字列いいえ定義されている場合、指定された値が名前に含まれたトークンを返します。
sort文字列いいえ定義されている場合、指定された値で結果を並べ替えます。使用できる値は、created_asc、created_desc、expires_asc、expires_desc、last_used_asc、last_used_desc、name_asc、name_descです。
state文字列いいえ定義されている場合、指定された状態のトークンを返します。使用できる値は、activeとinactiveです。

リクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/187/service_accounts/195/personal_access_tokens?sort=id_desc&search=token2b&created_before=2025-03-27"

レスポンス例:

[
    {
        "id": 187,
        "name": "service_accounts_token2b",
        "revoked": false,
        "created_at": "2025-03-26T14:42:51.084Z",
        "description": null,
        "scopes": [
            "api"
        ],
        "user_id": 195,
        "last_used_at": null,
        "active": true,
        "expires_at": null
    }
]

失敗したレスポンスの例:

  • 401: Unauthorized
  • 404 Group Not Found

グループのサービスアカウントのパーソナルアクセス・トークンを作成するには:

指定されたトップレベルグループ内の既存のサービスアカウントのパーソナルアクセストークンを作成します。

POST /groups/:id/service_accounts/:user_id/personal_access_tokens

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいトップレベルグループのIDまたはURLエンコードされたパス。
user_id整数はいサービスアカウントのID。
name文字列はいパーソナルアクセストークンの名前。
description文字列いいえパーソナルアクセストークンの説明。
scopes配列はい承認されたスコープの配列。使用可能な値のリストについては、パーソナルアクセストークンスコープを参照してください。
expires_at日付いいえISO形式（YYYY-MM-DD）のアクセストークンの有効期限。未指定の場合、日付は最大許容ライフタイム制限に設定されます。

リクエスト例:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens" --data "scopes[]=api,read_user,read_repository" --data "name=service_accounts_token"

レスポンス例:

{
  "id":6,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:47:13.900Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2024-06-12",
  "token":"<token_value>"
}

グループのサービスアカウントのパーソナルアクセストークンを失効するには:

指定されたトップレベルグループ内の既存のサービスアカウントのパーソナルアクセストークンを失効します。

このエンドポイントは、トップレベルグループでのみ機能します。

DELETE /groups/:id/service_accounts/:user_id/personal_access_tokens/:token_id

パラメータ:

属性型必須説明
id整数または文字列はいターゲットグループのIDまたはURLエンコードされたパス。
user_id整数はいサービスアカウントのID。
token_id整数はいトークンのID。

リクエスト例:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens/6"

成功した場合、204: No Contentを返します。

その他の発生しうる応答:

  • 正常に失効しなかった場合は400: Bad Request。
  • リクエストが承認されていない場合は401: Unauthorized。
  • リクエストが許可されていない場合は403: Forbidden。
  • アクセストークンが存在しない場合は404: Not Found。

グループのサービスアカウントのパーソナルアクセストークンをローテーションするには:

指定されたトップレベルグループ内の既存のサービスアカウントのパーソナルアクセストークンをローテーションします。これにより、1週間有効な新しいトークンが作成され、既存のトークンはすべて失効されます。

このエンドポイントは、トップレベルグループでのみ機能します。

POST /groups/:id/service_accounts/:user_id/personal_access_tokens/:token_id/rotate

パラメータ:

属性型必須説明
id整数または文字列はいターゲットグループのIDまたはURLエンコードされたパス。
user_id整数はいサービスアカウントのID。
token_id整数はいトークンのID。
expires_at日付いいえISO形式（YYYY-MM-DD）のアクセストークンの有効期限。GitLab 17.9で導入されました。トークンに有効期限が必要な場合、デフォルトは1週間です。不要な場合、デフォルトは最大許容ライフタイム制限になります。

リクエスト例:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens/6/rotate"

レスポンス例:

{
  "id":7,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:54:49.962Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2023-06-20",
  "token":"<token_value>"
}