Admin SCIM Settings API

This topic provides reference information about the /admin/scim-settings endpoint, which configures SCIM (System for Cross-domain Identity Management) provisioning for Terraform Enterprise.

Only site administrators can read, update, and disable SCIM settings.

List SCIM settings

GET /api/v2/admin/scim-settings

This endpoint returns the current SCIM settings.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/admin/scim-settings

Sample Response

{
    "data": {
        "id": "scim",
        "type": "scim-settings",
        "attributes": {
            "enabled": true,
            "paused": false,
            "site-admin-group-scim-id": "ef498761-2cc7-4569-9bd9-970a270dbb88",
            "site-admin-group-display-name": "Terraform Enterprise Admins"
        }
    }
}

Update SCIM settings

PATCH /api/v2/admin/scim-settings

This endpoint partially updates the SCIM configuration for the Terraform Enterprise instance. Include only the attributes you want to change. This endpoint is non-destructive. Use it to enable SCIM, pause or resume synchronization, or update the site administrator group mapping.

Terraform Enterprise rejects requests that set enabled to false with 422 Unprocessable Entity and leaves the current SCIM configuration unchanged. To enable SCIM, SAML must already be enabled and configured for a supported identity provider. Use DELETE /api/v2/admin/scim-settings to disable SCIM and reset SCIM data.

Request Body

This PATCH endpoint accepts a JSON object with any of the following properties in the request payload.

Include only the attributes you want to change.

Terraform Enterprise rejects requests that set enabled to false.

To enable SCIM, SAML must already be enabled and configured for a supported identity provider. Use DELETE /api/v2/admin/scim-settings to disable SCIM and reset SCIM data.

Sample Payload

{
    "data": {
        "type": "scim-settings",
        "attributes": {
            "enabled": true,
            "paused": false,
            "site-admin-group-scim-id": "ef498761-2cc7-4569-9bd9-970a270dbb88"
        }
    }
}

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://tfe.example.com/api/v2/admin/scim-settings

Sample Response

{
    "data": {
        "id": "scim",
        "type": "scim-settings",
        "attributes": {
            "enabled": true,
            "paused": false,
            "site-admin-group-scim-id": "ef498761-2cc7-4569-9bd9-970a270dbb88",
            "site-admin-group-display-name": "Terraform Enterprise Admins"
        }
    }
}

Rate limits

Terraform Enterprise limits requests to /api/v2/admin/scim-settings to 20 calls per second, including GET, PATCH, and DELETE.

When a caller exceeds this limit, Terraform Enterprise returns HTTP 429 using the standard admin API error format. Do not rely on a Retry-After header on this endpoint.

Disable SCIM

DELETE /api/v2/admin/scim-settings

This endpoint disables SCIM for the Terraform Enterprise instance. Disabling SCIM performs the following actions:

• Deletes all provisioned SCIM groups
• Deletes all SCIM group memberships
• Deletes all team-to-group links
• Deletes all SCIM user identities
• Revokes all SCIM tokens

Disabling SCIM also resets the settings resource to enabled=false, paused=false, and site-admin-group-scim-id=null.

Unlike setting site-admin-group-scim-id to null with PATCH, disabling SCIM does not revoke site administrator access that SCIM already granted.

When you disable SCIM, Terraform Enterprise preserves all linked teams and users, but you must manage them manually.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://tfe.example.com/api/v2/admin/scim-settings

Sample Response

{
    "data": {
        "id": "scim",
        "type": "scim-settings",
        "attributes": {
            "enabled": false,
            "paused": false,
            "site-admin-group-scim-id": null,
            "site-admin-group-display-name": null
        }
    }
}