Admin SCIM Groups API

This endpoint lists SCIM groups provisioned by your identity provider (IdP) with the SCIM 2.0 protocol. SCIM groups represent IdP groups that you can link to Terraform Enterprise teams, enabling automated team membership synchronization.

This is a read-only API endpoint. Your identity provider creates, updates, and deletes SCIM groups. Use this endpoint to view SCIM groups your identity provider has synced to Terraform Enterprise and made available for team linking.

This page documents the admin GET /api/v2/admin/scim-groups endpoint. For the public provisioning endpoints under /scim/v2/Groups, refer to the SCIM Groups API.

List SCIM groups

GET /api/v2/admin/scim-groups

This endpoint returns a paginated list of SCIM groups provisioned from your identity provider.

Query Parameters

This endpoint supports pagination with standard URL query parameters. You must use percent-style encoding [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`q`	Optional. Filters results by case-insensitive partial match on the SCIM group display name.
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns 20 SCIM groups per page.

Status	Response	Reason
200	JSON API document (`type: "scim-groups"`)	Successfully listed SCIM groups. Returns an empty collection when no groups match.
401	JSON API error object	Invalid or missing authentication token
404	JSON API error object	User unauthorized to perform action

Sample Request

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

Sample Request with Pagination

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  "https://tfe.example.com/api/v2/admin/scim-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20"

Sample Response

{
    "data": [
        {
            "id": "ef498761-2cc7-4569-9bd9-970a270dbb88",
            "type": "scim-groups",
            "attributes": {
                "name": "Engineering"
            }
        },
        {
            "id": "4dd65052-8e29-40b0-89c0-4f43f68c3859",
            "type": "scim-groups",
            "attributes": {
                "name": "Platform Team"
            }
        }
    ],
    "links": {
        "self": "https://tfe.example.com/api/v2/admin/scim-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "first": "https://tfe.example.com/api/v2/admin/scim-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "prev": null,
        "next": null,
        "last": "https://tfe.example.com/api/v2/admin/scim-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20"
    },
    "meta": {
        "pagination": {
            "current-page": 1,
            "page-size": 20,
            "prev-page": null,
            "next-page": null,
            "total-pages": 1,
            "total-count": 2
        }
    }
}

Response Attributes

The following attributes are included in the response for each SCIM group:

Attribute	Type	Description
`id`	string	The unique identifier for the SCIM group in Terraform Enterprise. Terraform Enterprise generates this value as a UUID when the group is provisioned with SCIM.
`type`	string	Always `"scim-groups"`.
`name`	string	The human-readable name of the group as provided by the identity provider.