SCIM Groups API reference

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

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

List SCIM groups

GET /scim/v2/:scim_configuration_id/Groups

This endpoint returns SCIM groups provisioned into the organization.

Path parameters

Parameter	Description
`:scim_configuration_id`	The external ID of the organization's SCIM configuration.

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. HCP Terraform caps this value at `200`. Set `count=0` to return only `totalResults`.

Response codes

The following table describes response codes HCP Terraform returns.

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
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://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/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/:scim_configuration_id/Groups/:id

This endpoint returns a single SCIM group resource.

Path parameters

Parameter	Description
`:scim_configuration_id`	The external ID of the organization's SCIM configuration.
`: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
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/:scim_configuration_id/Groups

This endpoint provisions a new SCIM group and automatically creates and links a team with the same name in the organization.

You can optionally include initial members. Group member references must use existing HCP Terraform SCIM user IDs.

The group name owners and sso are reserved so you should not use either one as a displayName. Requests using these names return HTTP 409 Conflict. Refer to Existing HCP Terraform teams for more information.

Path parameters

Parameter	Description
`:scim_configuration_id`	The external ID of the organization's SCIM configuration.

Response codes

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
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. HCP Terraform enforces uniqueness case-insensitively.
`externalId`	string	`null`	Optional identity-provider identifier for the group.
`members[]`	array	`[]`	Optional initial group membership list.
`members[].value`	string		A HCP Terraform 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://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/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/:scim_configuration_id/Groups/:id

This endpoint replaces the group's attributes and membership. HCP Terraform 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, HCP Terraform 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
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://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/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/:scim_configuration_id/Groups/:id

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

Path parameters

Parameter	Description
`:scim_configuration_id`	The external ID of the organization's SCIM configuration.
`:id`	The SCIM group ID returned in the group's `id` field.

Response codes

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.

You can use 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://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/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/:scim_configuration_id/Groups/:id

This endpoint deletes a SCIM group and the linked team in the organization. HCP Terraform returns an HTTP 404 if the group you're trying to delete does not exist.

Refer to Groups lifecycle for more information.

Path parameters

Parameter	Description
`:scim_configuration_id`	The external ID of the organization's SCIM configuration.
`:id`	The SCIM group ID returned in the group's `id` field.

Response codes

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
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://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/Groups/ef498761-2cc7-4569-9bd9-970a270dbb88"

Sample response

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

Response attributes

HCP Terraform 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 HCP Terraform.
`externalId`	string	The identity-provider identifier stored for the group.
`displayName`	string	The stored group name. HCP Terraform preserves the provided casing.
`members[]`	array	The current group membership. Omitted when the request uses `excludedAttributes=members`.
`members[].value`	string	A HCP Terraform 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 SCIM provisioning endpoints share a default rate limit of 30 requests per second. When you exceed this limit, HCP Terraform returns HTTP 429 with a Retry-After header.

SCIM Groups API reference

List SCIM groups

Path parameters

Query parameters

Response codes

Sample request

Sample response

Show a SCIM group

Path parameters

Query parameters

Create a SCIM group

Path parameters

Response codes

Request body

Sample payload

Sample request

Sample response

Replace a SCIM group

Request body

Sample Payload

Sample request

Sample response

Patch a SCIM group

Path parameters

Response codes

Request body

Sample payload

Sample request

Sample response

Delete a SCIM group

Path parameters

Response codes

Sample request

Sample response

Response attributes

Sample SCIM Group resource

Rate limiting

Sample SCIM `Group` resource