SCIM provisioning API endpoints
This topic provides reference information for HCP Terraform's SCIM 2.0 provisioning endpoints. Identity providers, such as Okta and Microsoft Entra ID, use these endpoints to provision users and groups into HCP Terraform.
You must authenticate with a SCIM provisioning token to call these endpoints. You can't use a user, team, or organization API token. Refer to the SCIM tokens API reference documentation for more information.
Authentication
SCIM provisioning endpoints require a SCIM bearer token in the Authorization header:
Authorization: Bearer <SCIM_TOKEN>
HCP Terraform 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 Manage SCIM tokens for provisioning token lifecycle guidance.
Discovery endpoints
HCP Terraform exposes the standard SCIM discovery endpoints. These endpoints use the same SCIM bearer token as the provisioning endpoints.
| Endpoint | Method | Description |
|---|---|---|
/scim/v2/:scim_configuration_id/ServiceProviderConfig | GET | Returns the SCIM service provider capabilities supported by HCP Terraform. |
/scim/v2/:scim_configuration_id/Schemas | GET | Returns the SCIM schemas supported by HCP Terraform. |
/scim/v2/:scim_configuration_id/ResourceTypes | GET | Returns the supported SCIM resource types. |
/scim/v2/:scim_configuration_id/ResourceTypes/User | GET | Returns metadata for the SCIM User resource type. |
/scim/v2/:scim_configuration_id/ResourceTypes/Group | GET | Returns metadata for the SCIM Group resource type. |
The :scim_configuration_id path parameter is the external ID of your organization's SCIM configuration. This value is provided in the Base URL field when you enable SCIM in your organization settings. Refer to Configure SCIM provisioning for details.
| 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 /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 following standard SCIM pagination parameters:
| 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. HCP Terraform caps this value at 200. Set count=0 to return only totalResults. |
Supported filters
HCP Terraform supports the following equality filters on SCIM list endpoints:
| Endpoint | Supported filters |
|---|---|
/scim/v2/:scim_configuration_id/Users | userName eq "value", externalId eq "value" |
/scim/v2/:scim_configuration_id/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.
API references
- Refer to the SCIM Users API for
/scim/v2/:scim_configuration_id/Usersrequest and response details. - Refer to the SCIM Groups API for
/scim/v2/:scim_configuration_id/Groupsrequest and response details.
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.
Request size limits
HCP Terraform applies a maximum request body size of 1 MB to SCIM POST, PUT, and PATCH requests on the Users and Groups endpoints.
Requests larger than this limit return HTTP 413 Payload Too Large.