Terraform
Public SCIM API reference
This topic provides reference information for Terraform Enterprise's public SCIM 2.0 endpoints under /scim/v2. Identity providers such as Okta and Microsoft Entra ID use these endpoints to provision users and groups into Terraform Enterprise.
Authenticate these endpoints with a SCIM provisioning token, not a site admin API token.
Authentication
Public SCIM endpoints require a SCIM bearer token in the Authorization header:
Authorization: Bearer <SCIM_TOKEN>
Terraform Enterprise returns SCIM responses with the application/scim+json content type and accepts JSON request bodies from common identity providers.
| Status | Response | Reason |
|---|---|---|
| 401 | SCIM 2.0 error response | Missing, invalid, expired, or non-SCIM token |
| 403 | SCIM 2.0 error response | SCIM provisioning is disabled or paused for /scim/v2/Users and /scim/v2/Groups |
Refer to the SCIM Tokens API for provisioning token lifecycle guidance.
Discovery Endpoints
Terraform Enterprise exposes the standard SCIM discovery endpoints below. These endpoints use the same SCIM bearer token as the provisioning endpoints.
| Endpoint | Method | Description |
|---|---|---|
/scim/v2/ServiceProviderConfig | GET | Returns the SCIM service provider capabilities supported by Terraform Enterprise. |
/scim/v2/Schemas | GET | Returns the SCIM schemas supported by Terraform Enterprise. |
/scim/v2/ResourceTypes | GET | Returns the supported SCIM resource types. |
/scim/v2/ResourceTypes/User | GET | Returns metadata for the SCIM User resource type. |
/scim/v2/ResourceTypes/Group | GET | Returns metadata for the SCIM Group resource type. |
| Status | Response | Reason |
|---|---|---|
| 200 | SCIM 2.0 discovery document | Successfully returned SCIM discovery metadata |
| 401 | SCIM 2.0 error response | Missing, invalid, expired, or non-SCIM token |
| 404 | SCIM 2.0 error response | Resource type not found for /scim/v2/ResourceTypes/:name |
Discovery endpoints authenticate the SCIM bearer token. When SCIM provisioning is paused, these endpoints remain available to callers with a valid SCIM token. If SCIM has been disabled and the provisioning token has been revoked, these endpoints return 401 Unauthorized.
Pagination
The list endpoints for users and groups support the standard SCIM pagination parameters below.
| Parameter | Default | Description |
|---|---|---|
startIndex | 1 | The first record to return. Values lower than 1 are treated as 1. |
count | 100 | The maximum number of records to return. Terraform Enterprise caps this value at 200. Set count=0 to return only totalResults. |
Supported Filters
Terraform Enterprise supports the following equality filters on public SCIM list endpoints:
| Endpoint | Supported filters |
|---|---|
/scim/v2/Users | userName eq "value", externalId eq "value" |
/scim/v2/Groups | displayName eq "value", externalId eq "value" |
Matches for userName and displayName are case-insensitive. Matches for externalId are exact. Unsupported filter expressions return HTTP 400 Bad Request.
Reference Pages
- Refer to the SCIM Users API for
/scim/v2/Usersrequest and response details. - Refer to the SCIM Groups API for
/scim/v2/Groupsrequest and response details.
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.
Request Size Limits
Terraform Enterprise applies a maximum request body size of 1 MB to public SCIM POST, PUT, and PATCH requests on /scim/v2/Users and /scim/v2/Groups.
Requests larger than this limit return HTTP 413 Payload Too Large.