SCIM Groups API reference

This topic provides reference information for the public SCIM group provisioning endpoints under /scim/v2/Groups.

For documentation about the admin endpoint that lists provisioned groups for team mapping, refer to Admin SCIM Groups API.

Refer to the Public SCIM API for shared authentication, discovery endpoints, pagination, supported filters, and shared rate limits.

List SCIM Groups

GET /scim/v2/Groups

This endpoint returns SCIM groups provisioned into Terraform Enterprise.

Query Parameters

Parameter	Default	Description
`filter`		Optional SCIM filter. Supported values are `displayName eq "value"` and `externalId eq "value"`. `displayName` matching is case-insensitive and `externalId` matching is exact.
`excludedAttributes`		Optional comma-separated list of attributes to omit from the response. Use `excludedAttributes=members` to omit group membership data.
`startIndex`	`1`	The first record to return.
`count`	`100`	The maximum number of records to return. Terraform Enterprise caps this value at `200`. Set `count=0` to return only `totalResults`.

Status	Response	Reason
200	SCIM 2.0 list response	Successfully listed SCIM groups
400	SCIM 2.0 error response	Unsupported filter expression or malformed request
401	SCIM 2.0 error response	Missing, invalid, expired, or non-SCIM token
403	SCIM 2.0 error response	SCIM is disabled or paused
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while listing SCIM groups

Sample Request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --request GET \
  "https://tfe.example.com/scim/v2/Groups?filter=displayName%20eq%20%22Engineering%22"

Sample Response

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 1,
    "Resources": [
        {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
            "id": "ef498761-2cc7-4569-9bd9-970a270dbb88",
            "externalId": "ext-eng-001",
            "displayName": "Engineering",
            "members": [
                {
                    "value": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
                    "display": "jane.doe@idp.com"
                }
            ],
            "meta": {
                "resourceType": "Group",
                "created": "2026-01-15T10:30:00Z",
                "lastModified": "2026-01-15T10:30:00Z"
            }
        }
    ]
}

Show a SCIM Group

GET /scim/v2/Groups/:id

This endpoint returns a single SCIM group resource.

Parameter	Description
`:id`	The SCIM group ID returned in the group's `id` field.

Query Parameters

Parameter	Description
`excludedAttributes`	Optional comma-separated list of attributes to omit from the response. Use `excludedAttributes=members` to omit group membership data.

Status	Response	Reason
200	SCIM 2.0 group resource	Successfully returned the group
401	SCIM 2.0 error response	Missing, invalid, expired, or non-SCIM token
403	SCIM 2.0 error response	SCIM is disabled or paused
404	SCIM 2.0 error response	Group not found
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while loading the group

Create a SCIM Group

POST /scim/v2/Groups

This endpoint provisions a new SCIM group. You can optionally include initial members. Group member references must use existing Terraform Enterprise SCIM user IDs.

Status	Response	Reason
201	SCIM 2.0 group resource	Successfully created the group
400	SCIM 2.0 error response	Malformed JSON or missing `displayName`
401	SCIM 2.0 error response	Missing, invalid, expired, or non-SCIM token
403	SCIM 2.0 error response	SCIM is disabled or paused
404	SCIM 2.0 error response	Referenced SCIM user not found
409	SCIM 2.0 error response	A group with the same `displayName` already exists
413	SCIM 2.0 error response	Request body too large or group exceeds the member limit
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while creating the group

Request Body

This endpoint accepts a SCIM 2.0 Group resource in the request body.

Properties without a default value are required.

Key path	Type	Default	Description
`schemas[]`	array		Include `"urn:ietf:params:scim:schemas:core:2.0:Group"`.
`displayName`	string		The SCIM group name. Terraform Enterprise enforces uniqueness case-insensitively.
`externalId`	string		Optional identity-provider identifier for the group.
`members[]`	array	`[]`	Optional initial group membership list.
`members[].value`	string		A Terraform Enterprise SCIM user ID to include in the group.

Sample Payload

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "Engineering",
    "externalId": "ext-eng-001",
    "members": [
        {
            "value": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126"
        }
    ]
}

Sample Request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --header "Accept: application/scim+json" \
  --header "Content-Type: application/scim+json" \
  --request POST \
  --data @payload.json \
  https://tfe.example.com/scim/v2/Groups

Sample Response

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "ef498761-2cc7-4569-9bd9-970a270dbb88",
    "externalId": "ext-eng-001",
    "displayName": "Engineering",
    "meta": {
        "resourceType": "Group",
        "created": "2026-01-15T10:30:00Z",
        "lastModified": "2026-01-15T10:30:00Z"
    },
    "members": [
        {
            "value": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
            "display": "jane.doe@idp.com"
        }
    ]
}

Replace a SCIM Group

PUT /scim/v2/Groups/:id

This endpoint replaces the group's attributes and membership. Terraform Enterprise treats members as the complete roster for the group. Setting members to an empty array clears the group's membership. If the request omits members, displayName, or externalId, Terraform Enterprise leaves the existing value unchanged.

Parameter	Description
`:id`	The SCIM group ID returned in the group's `id` field.

Status	Response	Reason
200	SCIM 2.0 group resource	Successfully replaced the group
400	SCIM 2.0 error response	Malformed JSON or invalid request body
401	SCIM 2.0 error response	Missing, invalid, expired, or non-SCIM token
403	SCIM 2.0 error response	SCIM is disabled or paused
404	SCIM 2.0 error response	Group or referenced SCIM user not found
409	SCIM 2.0 error response	A conflicting `displayName` already exists
413	SCIM 2.0 error response	Request body too large or group exceeds the member limit
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while replacing the group

Request Body

This endpoint accepts the same SCIM Group resource body shape as Create a SCIM Group.

Sample Payload

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "Engineering",
    "externalId": "ext-eng-001",
    "members": [
        {
            "value": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126"
        }
    ]
}

Sample Request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data @payload.json \
  https://tfe.example.com/scim/v2/Groups/ef498761-2cc7-4569-9bd9-970a270dbb88

Sample Response

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "ef498761-2cc7-4569-9bd9-970a270dbb88",
    "externalId": "ext-eng-001",
    "displayName": "Engineering",
    "members": [
        {
            "value": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
            "display": "jane.doe@idp.com"
        }
    ],
    "meta": {
        "resourceType": "Group",
        "created": "2026-01-15T10:30:00Z",
        "lastModified": "2026-01-15T10:45:00Z"
    }
}

Patch a SCIM Group

PATCH /scim/v2/Groups/:id

This endpoint partially updates a SCIM group with a SCIM PatchOp request body. Terraform Enterprise supports both full-member replacement and incremental add or remove operations.

Parameter	Description
`:id`	The SCIM group ID returned in the group's `id` field.

Status	Response	Reason
200	SCIM 2.0 group resource	Successfully updated the group
400	SCIM 2.0 error response	Malformed JSON, unsupported PATCH operation, or too many operations
401	SCIM 2.0 error response	Missing, invalid, expired, or non-SCIM token
403	SCIM 2.0 error response	SCIM is disabled or paused
404	SCIM 2.0 error response	Group or referenced SCIM user not found
409	SCIM 2.0 error response	A conflicting `displayName` already exists
413	SCIM 2.0 error response	Request body too large or group exceeds the member limit
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while updating the group

Request Body

Key path	Type	Description
`schemas[]`	array	Include `"urn:ietf:params:scim:api:messages:2.0:PatchOp"`.
`Operations[]`	array	Up to 100 patch operations.
`Operations[].op`	string	Supported values are `Add`, `Replace`, and `Remove`.
`Operations[].path`	string	Supported targeted paths are `members`, `displayName`, and `externalId`. `Remove` supports `members[value eq "<scim-user-id>"]`.
`Operations[].value`	mixed	The replacement value, added value, or bulk attribute object.

Terraform Enterprise supports the following PATCH operations:

Add on members, where value contains one or more SCIM user IDs.
Remove on members[value eq "<scim-user-id>"].
Replace on displayName, externalId, and members.
Replace without a path, where value is an object containing any combination of displayName, externalId, and members.

Removing a member that is not currently in the group succeeds without error.

Sample Payload

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "Add",
            "path": "members",
            "value": [
                {
                    "value": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126"
                }
            ]
        }
    ]
}

Sample Request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data @payload.json \
  https://tfe.example.com/scim/v2/Groups/ef498761-2cc7-4569-9bd9-970a270dbb88

Sample Response

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "ef498761-2cc7-4569-9bd9-970a270dbb88",
    "externalId": "ext-eng-001",
    "displayName": "Engineering",
    "members": [
        {
            "value": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
            "display": "jane.doe@idp.com"
        }
    ],
    "meta": {
        "resourceType": "Group",
        "created": "2026-01-15T10:30:00Z",
        "lastModified": "2026-01-15T10:50:00Z"
    }
}

Delete a SCIM Group

DELETE /scim/v2/Groups/:id

This endpoint deletes a SCIM group. Terraform Enterprise treats delete as idempotent and returns HTTP 204 No Content whether or not the group exists.

If the deleted group is configured as the site admin group, Terraform Enterprise clears the site admin group mapping but does not revoke site administrator access that SCIM already granted.

Parameter	Description
`:id`	The SCIM group ID returned in the group's `id` field.

Status	Response	Reason
204	No Content	Successfully deleted the group, or the group did not exist
401	SCIM 2.0 error response	Missing, invalid, expired, or non-SCIM token
403	SCIM 2.0 error response	SCIM is disabled or paused
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while deleting the group

Sample Request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --request DELETE \
  https://tfe.example.com/scim/v2/Groups/ef498761-2cc7-4569-9bd9-970a270dbb88

Sample Response

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

Response Attributes

Terraform Enterprise returns the following attributes in a SCIM group resource.

Attribute	Type	Description
`schemas[]`	array	Always includes `"urn:ietf:params:scim:schemas:core:2.0:Group"`.
`id`	string	The SCIM group ID returned by Terraform Enterprise.
`externalId`	string	The identity-provider identifier stored for the group.
`displayName`	string	The stored group name. Terraform Enterprise preserves the provided casing.
`members[]`	array	The current group membership. Omitted when the request uses `excludedAttributes=members`.
`members[].value`	string	A Terraform Enterprise SCIM user ID.
`members[].display`	string	The SCIM `userName` for the referenced member.
`meta.resourceType`	string	Always `"Group"`.
`meta.created`	timestamp	The time the group was created.
`meta.lastModified`	timestamp	The time the group was last updated.

Sample SCIM Group Resource

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "ef498761-2cc7-4569-9bd9-970a270dbb88",
    "externalId": "ext-eng-001",
    "displayName": "Engineering",
    "members": [
        {
            "value": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
            "display": "jane.doe@idp.com"
        }
    ],
    "meta": {
        "resourceType": "Group",
        "created": "2026-01-15T10:30:00Z",
        "lastModified": "2026-01-15T10:30:00Z"
    }
}

Rate Limiting

The public /scim/v2/Users and /scim/v2/Groups endpoints share a default rate limit of 10 requests per second. When you exceed this limit, Terraform Enterprise returns HTTP 429 with a Retry-After header.