Switchboard customer API

Use this API to retrieve the status and maintenance windows of your GitLab Dedicated instance, and to update the configuration that you can edit in the Switchboard console.

The API returns data only for the instance that you have tenant administrator access to. You do not put the instance in the path. The API gets it from your access.

All endpoints use this base URL:

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

If your Switchboard console has a different URL, use the URL of the console that you sign in to. The client ID and the endpoint paths are the same for all consoles.

Prerequisites:

• You must have tenant administrator access to your instance in Switchboard.

Authentication

Each request must have a Switchboard OAuth 2.0 access token in the Authorization header.

Switchboard gives tokens through the OAuth 2.0 authorization code flow with Proof Key for Code Exchange (PKCE). Use the public client switchboard_customer_api_auth. This client has no client secret. Request the read_write scope.

An access token expires after 24 hours. The token response also has a refresh token. Use the refresh token to get a new access token without a sign-in in the browser.

Get an access token

You can use any OAuth 2.0 client that follows the standard. This example uses oauth2c.

To get an access token:

1. Run this command:

   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

   The command opens a browser.

2. Sign in to Switchboard.

3. Approve the request.

The command gets the callback on http://localhost:3290/callback and shows the access token. Send the token with each request:

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

Refresh an access token

To get a new token pair without a sign-in in the browser, send the refresh token to the token endpoint:

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>"

Each refresh returns a new refresh token. Keep the newest refresh token.

You can refresh tokens for a maximum of 30 days after the first sign-in in the browser. After 30 days, or if Switchboard revokes the token, the token endpoint returns invalid_grant. To continue, get a new access token with a sign-in in the browser.

Rate limits

Switchboard counts requests for each access token and for each source IP address, in windows of one minute.

When a limit applies, the response has these headers for the limit that is nearest to its maximum:

If a response does not have these headers, no limit applied to the request. Use the values in the headers. Do not use the numbers in the table as fixed values.

When a request is over a limit, the API returns 429 Too Many Requests. The Retry-After header gives the number of seconds to wait. A request that you make while you are over a limit also counts against the limit. If your client continues to send requests, it stays blocked until the window resets.

Errors

All endpoints can return these status codes:

An error response has a message attribute. Some errors also have an errors attribute with more detail.

Pagination

List endpoints return one page of items. Use these attributes to select a page:

The response has an items array and a meta object:

Retrieve instance details

Retrieves details about your instance.

GET /tenant

If successful, returns 200 OK and the following response attributes:

Example request:

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

Example response:

{
  "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"]
  }
}

Retrieve SLA status

Retrieves the most recent availability status of your instance. The status shows the same data as the Health page in Switchboard.

GET /tenant/sla_status

If successful, returns 200 OK and the following response attributes:

The status attribute has one of these values:

The reason attribute has one of these values:

Example request:

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

Example response:

{
  "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" }
  ]
}

List all maintenance windows

Lists all planned maintenance windows of your instance. The list has windows in the future and windows that are complete.

GET /tenant/maintenances

Supported attributes:

If successful, returns 200 OK and an items array. Each item has these attributes:

If the scope value is not known, the API returns 422 Unprocessable Entity.

Example request:

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

Example response:

{
  "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 }
}

List all configuration changes

Lists all configuration changes of your instance, the most recent change first. Each change shows what changed, when, and if the change is on your instance.

GET /tenant/config_changes

Supported attributes:

If successful, returns 200 OK and an items array. Each item has these attributes:

Example request:

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

Example response:

{
  "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 }
}

Configuration

These endpoints retrieve and update the settings that you can edit in the Switchboard console. Each endpoint matches one section of the console.

The PUT endpoints replace the full section. Send the full configuration that you want. Switchboard removes the items that you do not send. To change one item, get the section, change the item, and send the full section back. The PUT endpoints accept the response of the related GET endpoint without changes. They ignore the attributes that Switchboard sets.

Switchboard records each change in the configuration changes of your instance. Changes to the contact information are not in this record.

Retrieve IP allowlist

Retrieves the IP allowlist of your instance.

GET /tenant/ip_allowlist

If successful, returns 200 OK and the following response attributes:

Replace IP allowlist

Replaces the IP allowlist of your instance.

PUT /tenant/ip_allowlist

Supported attributes:

If successful, returns 200 OK and the updated allowlist.

Example request:

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"

Retrieve contact information

Retrieves the operational email addresses that GitLab uses to contact you about your instance.

GET /tenant/contact_information

If successful, returns 200 OK and the following response attributes:

Replace contact information

Replaces the operational email addresses of your instance.

PUT /tenant/contact_information

Supported attributes:

If successful, returns 200 OK and the updated contact information.

GitLab sets the internal contacts and the assigned support engineers. You cannot read or change them with this API.

Retrieve resource access settings

Retrieves the AWS principals that can read the application log bucket of your instance.

GET /tenant/resource_access

If successful, returns 200 OK and the following response attributes:

Replace resource access settings

Replaces the AWS principals that can read the application log bucket of your instance.

PUT /tenant/resource_access

Supported attributes:

If successful, returns 200 OK and the updated settings.

List all custom certificate authorities

Lists all custom certificate authorities that your instance trusts.

GET /tenant/custom_certificate_authorities

If successful, returns 200 OK and an array. Each item has these attributes:

Replace custom certificate authorities

Replaces the custom certificate authorities that your instance trusts.

PUT /tenant/custom_certificate_authorities

Supported attributes:

If successful, returns 200 OK and the updated list.

If one certificate is not valid or is expired, Switchboard does not accept the request. The error shows the index of the certificate.

List all SAML SSO providers

Lists all SAML single sign-on (SSO) providers of your instance, the oldest first.

GET /tenant/saml_providers

If successful, returns 200 OK and an array of providers. Each provider has the provider attributes and an id.

Retrieve a SAML SSO provider

Retrieves one SAML SSO provider of your instance.

GET /tenant/saml_providers/:id

If successful, returns 200 OK and the provider. If the provider does not exist, returns 404 Not Found.

Create a SAML SSO provider

Creates a SAML SSO provider on your instance.

POST /tenant/saml_providers

Send the provider attributes.

If successful, returns 201 Created and the new provider.

Replace a SAML SSO provider

Replaces one SAML SSO provider of your instance.

PUT /tenant/saml_providers/:id

Send the full provider. If you do not send an optional attribute, Switchboard clears it. For example, if you do not send admin_groups, Switchboard removes the mapping of groups to administrators.

If successful, returns 200 OK and the updated provider.

Delete a SAML SSO provider

Deletes one SAML SSO provider from your instance.

DELETE /tenant/saml_providers/:id

If successful, returns 204 No Content.

SAML SSO provider attributes

For more information about these settings, see SAML SSO for GitLab Dedicated.

Related topics

• GitLab Dedicated instance details
• GitLab Dedicated maintenance operations