Admin Team SCIM Group Mapping API

Use the Team SCIM Group Mapping API to link SCIM groups from your identity provider (IdP) to Terraform Enterprise teams. When a SCIM group is linked to a team, Terraform Enterprise automatically synchronizes team membership based on the group membership in your IdP.

This API lets you take the following actions:

• Map a SCIM group to a Terraform Enterprise team, enabling automatic membership synchronization
• Remove a SCIM group mapping from a team, stopping automatic synchronization
• Pause synchronization for a linked SCIM group while retaining the mapping
• Resume synchronization after a pause

Only site administrators can manage these endpoints. Use the SCIM Settings API to enable or disable SCIM provisioning for the instance.

Map a SCIM group to a team

POST /api/v2/admin/teams/:external_id/scim-group-mapping

This endpoint maps a SCIM group to a Terraform Enterprise team. Once the team is linked, Terraform Enterprise synchronizes team membership based on the SCIM group membership set in your identity provider. Terraform Enterprise replaces existing human user memberships with the SCIM group members and preserves any existing service account memberships.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Sample Payload

{
    "data": {
        "type": "scim-group-mapping",
        "attributes": {
            "scim-group-id": "ef498761-2cc7-4569-9bd9-970a270dbb88"
        }
    }
}

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://tfe.example.com/api/v2/admin/teams/team-6p5jTwJQXwqZBncC/scim-group-mapping

Sample Response

A successful request returns a 204 No Content response with no body.

Remove a SCIM group mapping from a team

DELETE /api/v2/admin/teams/:external_id/scim-group-mapping

This endpoint removes the mapping between a SCIM group and a Terraform Enterprise team. After removal, Terraform Enterprise stops synchronizing team membership from the identity provider. Existing team members remain on the team, but SCIM no longer manages them.

Sample Request

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

Sample Response

A successful request returns a 204 No Content response with no body.

Pause or resume SCIM synchronization

PATCH /api/v2/admin/teams/:external_id/scim-group-mapping

This endpoint pauses or resumes synchronization for a linked SCIM group while keeping the mapping in place. While paused, Terraform Enterprise does not apply membership changes from the identity provider to the team. When you resume synchronization, Terraform Enterprise immediately reconciles the team's membership with the current linked SCIM group state.

If the requested scim-sync-paused value already matches the current state, Terraform Enterprise returns 204 No Content and leaves the existing synchronization state unchanged. Repeating the same pause or resume request is safe.

Request Body

This PATCH endpoint requires a JSON object with the following properties as a request payload.

Sample Payload

{
    "data": {
        "type": "scim-group-mapping",
        "attributes": {
            "scim-sync-paused": true
        }
    }
}

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/teams/team-6p5jTwJQXwqZBncC/scim-group-mapping

Sample Response

A successful request returns a 204 No Content response with no body.

Team attributes for SCIM-linked teams

When SCIM is enabled on Terraform Enterprise, team API responses include the following SCIM-related attributes for all teams. The values indicate whether a given team is linked to a SCIM group.

Rate limits

Terraform Enterprise applies a rate limit of 10 requests per minute to the following team SCIM mapping operations. These limits are keyed per authenticated site administrator:

• Map or remove a SCIM group mapping, such as POST and DELETE calls to /api/v2/admin/teams/:external_id/scim-group-mapping
• Pause or resume synchronization, such as PATCH calls to /api/v2/admin/teams/:external_id/scim-group-mapping

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

Restrictions for SCIM-linked teams

When a team is linked to a SCIM group, certain operations are restricted to maintain the identity provider as the source of truth. Pausing synchronization preserves the link, and direct membership updates remain blocked until you remove it. For related team behavior, refer to the Teams API reference and the Team Membership API.

Blocked operations

The following API operations are blocked for SCIM-linked teams:

• Adding or removing users through /teams/:team_id/relationships/users or /teams/:team_id/relationships/organization-memberships
• Deleting the team using DELETE /teams/:team_id
• Changing the team name using PATCH /teams/:team_id

Allowed operations

The following operations remain available for SCIM-linked teams:

• Modifying the team's organization-level permissions
• Changing the team's visibility setting

Terraform Enterprise also accepts PATCH /teams/:team_id requests that include sso-team-id, but ignores changes to sso-team-id while the team remains linked to a SCIM group.