スイッチボードカスタマーAPI

このAPIを使用して、GitLab Dedicatedインスタンスのステータスとメンテナンスウィンドウを取得し、Switchboardコンソールで編集できる設定を更新します。

このAPIは、テナント管理者アクセス権を持つインスタンスのデータのみを返します。パスにインスタンスを指定しません。APIはアクセス権からインスタンスを取得します。

すべてのエンドポイントは、このベースURLを使用します:

https://console.gitlab-dedicated.com/api/customer/v1

Switchboardコンソールが異なるURLを使用している場合は、サインインするコンソールのURLを使用します。クライアントIDとエンドポイントパスは、すべてのコンソールで同じです。

前提条件:

• Switchboardでインスタンスのテナント管理者アクセス権が必要です。

認証

各リクエストには、AuthorizationヘッダーにSwitchboard OAuth 2.0アクセストークンが必要です。

SwitchboardはProof Key for Code Exchange（PKCE）を使用したOAuth 2.0認可コードフローを通じてトークンを提供します。パブリッククライアントswitchboard_customer_api_authを使用します。このクライアントにはクライアントシークレットがありません。read_writeスコープをリクエストします。

アクセストークンは24時間後に失効します。トークンレスポンスにはリフレッシュトークンも含まれます。リフレッシュトークンを使用すると、ブラウザでのサインインなしで新しいアクセストークンを取得できます。

アクセストークンを取得する

標準に準拠した任意のOAuth 2.0クライアントを使用できます。この例ではoauth2cを使用します。

アクセストークンを取得するには、次の手順に従います:

1. このコマンドを実行します:

   shell

   oauth2c https://console.gitlab-dedicated.com \
     --client-id switchboard_customer_api_auth \
     --grant-type authorization_code \
     --response-types code \
     --response-mode query \
     --auth-method none \
     --scopes read_write \
     --pkce \
     --redirect-url http://localhost:3290/callback \
     --authorization-endpoint https://console.gitlab-dedicated.com/oauth/authorize \
     --token-endpoint https://console.gitlab-dedicated.com/oauth/token

   このコマンドを実行すると、ブラウザが開きます。

2. Switchboardにサインインします。

3. リクエストを承認します。

このコマンドはhttp://localhost:3290/callbackでコールバックを取得し、アクセストークンを表示します。各リクエストでトークンを送信します:

curl --request GET \
  --header "Authorization: Bearer <your_access_token>" \
  --url "https://console.gitlab-dedicated.com/api/customer/v1/tenant/sla_status"

アクセストークンを更新する

ブラウザでのサインインなしで新しいトークンペアを取得するには、リフレッシュトークンをトークンエンドポイントに送信します:

curl --request POST \
  --url "https://console.gitlab-dedicated.com/oauth/token" \
  --data "grant_type=refresh_token" \
  --data "client_id=switchboard_customer_api_auth" \
  --data "refresh_token=<your_refresh_token>"

更新のたびに、新しいリフレッシュトークンが返されます。最新のリフレッシュトークンを保持してください。

ブラウザでの最初のサインインから最大30日間、トークンを更新できます。30日経過後、またはSwitchboardがトークンを失効させた場合、トークンエンドポイントはinvalid_grantを返します。続行するには、ブラウザでサインインして新しいアクセストークンを取得します。

レート制限

Switchboardは、各アクセストークンと各送信元IPアドレスのリクエストを1分間のウィンドウでカウントします。

制限が適用される場合、レスポンスには最大値に最も近い制限のヘッダーが含まれます:

レスポンスにこれらのヘッダーがない場合、リクエストに制限は適用されていません。ヘッダー内の値を使用してください。表の数値を固定値として使用しないでください。

リクエストが制限を超えた場合、APIは429 Too Many Requestsを返します。Retry-Afterヘッダーには、待機する秒数が示されます。制限を超えている間に行ったリクエストも、制限にカウントされます。クライアントがリクエストの送信を続ける場合、ウィンドウがリセットされるまでブロックされたままになります。

エラー

すべてのエンドポイントは、これらのステータスコードを返すことがあります:

エラーレスポンスにはmessage属性があります。エラーによっては、詳細情報を含むerrors属性もあります。

ページネーション

リストエンドポイントは、項目の1ページ分を返します。これらの属性を使用してページを選択します:

レスポンスにはitems配列とmetaオブジェクトが含まれます:

インスタンスの詳細を取得する

インスタンスの詳細を取得します。

GET /tenant

成功した場合、200 OKと次のレスポンス属性を返します:

リクエスト例:

curl --request GET \
  --header "Authorization: Bearer <your_access_token>" \
  --url "https://console.gitlab-dedicated.com/api/customer/v1/tenant"

レスポンス例:

{
  "identifier": "example1a2b3c",
  "name": "Example Corp",
  "external_url": "https://example.gitlab-dedicated.com",
  "gitlab_version": "19.3.3",
  "prerelease_version": null,
  "reference_architecture_label": "Up to 10,000 users (XL)",
  "ever_deployed": true,
  "regions": {
    "primary": "eu-west-1",
    "backup": "eu-central-1",
    "sites": ["eu-west-1"]
  }
}

SLAステータスを取得する

インスタンスの最新の可用性ステータスを取得します。このステータスは、Switchboardの健全性ページと同じデータを表示します。

GET /tenant/sla_status

成功した場合、200 OKと次のレスポンス属性を返します:

status属性には、次のいずれかの値があります:

reason属性には、次のいずれかの値があります:

リクエスト例:

curl --request GET \
  --header "Authorization: Bearer <your_access_token>" \
  --url "https://console.gitlab-dedicated.com/api/customer/v1/tenant/sla_status"

レスポンス例:

{
  "data_available": true,
  "status": "up",
  "data_as_of": "2026-10-08T09:41:00.000Z",
  "reason": null,
  "covered_experiences": [
    { "covered_experience": "web", "status": "up", "data_as_of": "2026-10-08T09:41:00.000Z" },
    { "covered_experience": "git_operations", "status": "up", "data_as_of": "2026-10-08T09:41:00.000Z" }
  ]
}

すべてのメンテナンスウィンドウを一覧表示する

インスタンスの計画されたすべてのメンテナンスウィンドウを一覧表示します。このリストには、今後のウィンドウと完了したウィンドウが含まれます。

GET /tenant/maintenances

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

成功すると、200 OKとitems配列が返されます。各項目には、次の属性があります:

scopeの値が不明な場合、APIは422 Unprocessable Entityを返します。

リクエスト例:

curl --request GET \
  --header "Authorization: Bearer <your_access_token>" \
  --url "https://console.gitlab-dedicated.com/api/customer/v1/tenant/maintenances?scope=upcoming"

レスポンス例:

{
  "items": [
    {
      "id": 4821,
      "start_at": "2026-10-11T21:00:00.000Z",
      "end_at": "2026-10-12T01:00:00.000Z",
      "started_at": null,
      "completed_at": null,
      "status": "planned",
      "approval_status": "approved",
      "emergency": false,
      "gitlab_version": "19.3.4",
      "previous_gitlab_version": "19.3.3",
      "gitlab_version_pinned": false
    }
  ],
  "meta": { "current_page": 1, "total": 1, "total_pages": 1 }
}

すべての設定変更を一覧表示する

インスタンスのすべての設定変更を、最新の変更から順に一覧表示します。各変更には、何が、いつ変更されたか、そしてその変更がインスタンスに適用されているかどうかが表示されます。

GET /tenant/config_changes

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

成功すると、200 OKとitems配列が返されます。各項目には、次の属性があります:

リクエスト例:

curl --request GET \
  --header "Authorization: Bearer <your_access_token>" \
  --url "https://console.gitlab-dedicated.com/api/customer/v1/tenant/config_changes?per_page=20"

レスポンス例:

{
  "items": [
    {
      "id": 912,
      "config_type": "IP allowlist",
      "status": "deployed",
      "requested_at": "2026-10-06T14:02:11.000Z",
      "completed_at": "2026-10-06T14:20:47.000Z"
    }
  ],
  "meta": { "current_page": 1, "total": 1, "total_pages": 1 }
}

設定

これらのエンドポイントは、Switchboardコンソールで編集できる設定を取得および更新します。各エンドポイントは、コンソールの1つのセクションに対応します。

PUTエンドポイントは、セクション全体を置き換えます。必要な設定全体を送信してください。Switchboardは、送信されなかった項目を削除します。1つの項目を変更するには、セクションを取得し、項目を変更して、セクション全体を送り返します。PUTエンドポイントは、関連するGETエンドポイントのレスポンスをそのまま受け付けます。これらは、Switchboardが設定する属性を無視します。

Switchboardは、インスタンスの設定変更の各変更を記録します。連絡先情報への変更はこの記録には含まれません。

IP許可リストを取得する

インスタンスのIP許可リストを取得します。

GET /tenant/ip_allowlist

成功した場合、200 OKと次のレスポンス属性を返します:

IP許可リストを置き換える

インスタンスのIP許可リストを置き換えます。

PUT /tenant/ip_allowlist

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

成功すると、200 OKと更新された許可リストが返されます。

リクエスト例:

curl --request PUT \
  --header "Authorization: Bearer <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"enabled": true, "addresses": [{"address": "203.0.113.0/24", "description": "Office"}]}' \
  --url "https://console.gitlab-dedicated.com/api/customer/v1/tenant/ip_allowlist"

連絡先情報を取得する

GitLabがインスタンスに関する連絡に使用する運用メールアドレスを取得します。

GET /tenant/contact_information

成功した場合、200 OKと次のレスポンス属性を返します:

連絡先情報を置き換える

インスタンスの運用メールアドレスを置き換えます。

PUT /tenant/contact_information

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

成功すると、200 OKと更新された連絡先情報が返されます。

GitLabは、内部連絡先および割り当てられたサポートエンジニアを設定します。このAPIでそれらを読み取ったり変更したりすることはできません。

リソースアクセス設定を取得する

インスタンスのアプリケーションログバケットを読み取ることができるAWSプリンシパルを取得します。

GET /tenant/resource_access

成功した場合、200 OKと次のレスポンス属性を返します:

リソースアクセス設定を置き換える

インスタンスのアプリケーションログバケットを読み取ることができるAWSプリンシパルを置き換えます。

PUT /tenant/resource_access

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

成功すると、200 OKと更新された設定が返されます。

すべてのカスタム証明機関を一覧表示する

インスタンスが信頼するすべてのカスタム証明機関を一覧表示します。

GET /tenant/custom_certificate_authorities

成功すると、200 OKと配列が返されます。各項目には、次の属性があります:

カスタム証明機関を置き換える

インスタンスが信頼するカスタム証明機関を置き換えます。

PUT /tenant/custom_certificate_authorities

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

成功すると、200 OKと更新されたリストが返されます。

1つの証明書が無効であるか期限切れである場合、Switchboardはリクエストを受け入れません。エラーには証明書のインデックスが表示されます。

すべてのSAML SSOプロバイダーを一覧表示する

インスタンスのすべてのSAMLシングルサインオン（SSO）プロバイダーを、最も古いものから順に一覧表示します。

GET /tenant/saml_providers

成功すると、200 OKとプロバイダーの配列が返されます。各プロバイダーには、プロバイダー属性とidがあります。

SAML SSOプロバイダーを取得する

インスタンスのSAML SSOプロバイダーを1つ取得します。

GET /tenant/saml_providers/:id

成功すると、200 OKとプロバイダーが返されます。プロバイダーが存在しない場合は404 Not Foundが返されます。

SAML SSOプロバイダーを作成する

インスタンスにSAML SSOプロバイダーを作成します。

POST /tenant/saml_providers

プロバイダー属性を送信します。

成功すると、201 Createdと新しいプロバイダーが返されます。

SAML SSOプロバイダーを置き換える

インスタンスのSAML SSOプロバイダーを1つ置き換えます。

PUT /tenant/saml_providers/:id

プロバイダー全体を送信します。オプションの属性を送信しない場合、Switchboardはその属性をクリアします。たとえば、admin_groupsを送信しない場合、Switchboardは管理者へのグループのマッピングを削除します。

成功すると、200 OKと更新されたプロバイダーが返されます。

SAML SSOプロバイダーを削除する

インスタンスからSAML SSOプロバイダーを1つ削除します。

DELETE /tenant/saml_providers/:id

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

SAML SSOプロバイダー属性

これらの設定の詳細については、GitLab Dedicated用SAML SSOを参照してください。

関連トピック

• GitLab Dedicatedインスタンスの詳細
• GitLab Dedicatedのメンテナンス操作