Manage SCIM provisioning

This page explains how to maintain the site-level SCIM configuration after initial setup.

Overview

Use this page for the following operational tasks:

Pause or resume SCIM provisioning for the Terraform Enterprise instance.
Configure or update the site admin group.
Rotate SCIM tokens.
Disable SCIM when necessary.

For the initial setup workflow, refer to Configure SCIM provisioning.

Pause and resume SCIM provisioning

Pausing SCIM is different from disabling it. When SCIM is paused, Terraform Enterprise keeps the existing SCIM data and tokens, but stops processing provisioning requests from your identity provider.

Pause SCIM provisioning

Open Site Admin > SCIM.
Open Manage.
Click Pause SCIM provisioning.
Confirm the action.

While SCIM is paused:

Existing SCIM users, groups, team links, and tokens stay in place.
Public provisioning requests to /scim/v2/Users and /scim/v2/Groups return 403 Forbidden.
Linked teams stop receiving SCIM updates.
Users can still sign in with SAML.

Resume SCIM provisioning

Open Site Admin > SCIM.
Open Manage and click Resume SCIM provisioning.

When you resume SCIM:

Terraform Enterprise starts processing provisioning requests again.
SCIM-linked teams can receive updates again.
Team links that were paused individually stay paused until you resume them.

For team-level pause and resume behavior, refer to Link SCIM groups to teams.

Configure site admin group

Use a SCIM group to grant site administrator access automatically.

Open Site Admin > SCIM.
In Site Admin IdP Group, select the SCIM group to use for site admins.
Click Update site admin provisioning.

Site admin group behavior

Setting or changing the selected SCIM group updates site admin access immediately for the current members of the mapped group.
Members added to the selected SCIM group through later SCIM group updates also gain site admin access.
Suspended users in the selected SCIM group do not receive site admin access until they are reactivated.
When you change the site admin group, Terraform Enterprise revokes site admin access from users in the previous mapped group who currently have the SITE_ADMIN role, then grants site admin access to the current members of the new mapped group.
Clearing the site admin group removes the mapping. Existing site administrator grants are not automatically revoked.
A SCIM group used for site admin access cannot also be linked to a Terraform Enterprise team.
When SCIM is enabled, use this setting to manage site admin access. Terraform Enterprise does not use SAML site admin attributes for site admin provisioning.

We still recommend keeping at least one non-SSO admin account for recovery.

Rotate SCIM tokens

To rotate a SCIM token:

Generate a new token.
Update your identity provider to use the new token.
Verify that provisioning still works.
Delete the old token.

Deleting a token revokes it immediately. SCIM requests that still use that token fail until your identity provider starts using another valid token.

For detailed token lifecycle guidance, refer to Tokens.

Disable SCIM provisioning

Disabling SCIM is different from pausing it. Disabling removes the SCIM configuration from Terraform Enterprise.

When you disable SCIM, Terraform Enterprise:

deletes all SCIM groups
deletes all SCIM group memberships
deletes all team-to-SCIM-group links
deletes all SCIM identities
revokes all SCIM tokens

Terraform Enterprise keeps:

existing users
existing teams and their permissions
organization memberships
existing site administrator grants

Users can still sign in with SAML after SCIM is disabled.

Open Site Admin > SCIM.
Open Manage and click Disable SCIM provisioning.
Review the warning.
Confirm the action.
Remove or disable the SCIM connection in your identity provider.

If you enable SCIM again later, you must generate new tokens and reconnect your identity provider.

If you disable SCIM through the admin settings API, use DELETE /api/v2/admin/scim-settings. Do not use PATCH with enabled=false; Terraform Enterprise rejects that request.

After the delete completes, Terraform Enterprise resets the SCIM settings to enabled=false, paused=false, and clears the configured site admin group without revoking existing site administrator grants. Repeating the delete while SCIM is already disabled is safe and leaves SCIM in the same disabled state.