SCIM Users API reference

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

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

List SCIM users

The following endpoint returns SCIM-managed users in the organization. Without a filter, HCP Terraform returns a paginated SCIM list response.

GET /scim/v2/:scim_configuration_id/Users

Query parameters

Parameter	Default	Description
`filter`		Optional SCIM filter. Supported values are `userName eq "value"` and `externalId eq "value"`. Matches for `userName` are case-insensitive. Matches for `externalId` are exact.
`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

Status	Response	Reason
200	SCIM 2.0 list response	Successfully listed SCIM users
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 users

Sample request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --request GET \
  "https://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/Users?filter=userName%20eq%20%22user%40example.com%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:User"],
            "id": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
            "externalId": "ext-999",
            "userName": "user@example.com",
            "name": {
                "formatted": "user"
            },
            "emails": [
                {
                    "value": "user@example.com",
                    "primary": true
                }
            ],
            "active": true,
            "meta": {
                "resourceType": "User",
                "created": "2026-01-15T10:30:00Z",
                "lastModified": "2026-01-15T10:30:00Z"
            }
        }
    ]
}

Show a SCIM user

The following endpoint returns a single SCIM user resource in the organization.

GET /scim/v2/:scim_configuration_id/Users/:id

Path parameters

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

Response codes

Status	Response	Reason
200	SCIM 2.0 user resource	Successfully returned the user
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	User not found
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while loading the user

Sample request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --request GET \
  "https://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/Users/52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126"

Sample response

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
    "externalId": "ext-999",
    "userName": "user@example.com",
    "name": {
        "formatted": "user"
    },
    "emails": [
        {
            "value": "user@example.com",
            "primary": true
        }
    ],
    "active": true,
    "meta": {
        "resourceType": "User",
        "created": "2026-01-15T10:30:00Z",
        "lastModified": "2026-01-15T10:30:00Z"
    }
}

Create a SCIM user

The following endpoint provisions a new SCIM user. If the organization already has a member with the same email address, HCP Terraform links that existing user to the new SCIM identity instead of creating a duplicate user record.

POST /scim/v2/:scim_configuration_id/Users

Status	Response	Reason
201	SCIM 2.0 user resource	Successfully created or linked the user
400	SCIM 2.0 error response	Malformed JSON or missing email data
401	SCIM 2.0 error response	Missing, invalid, expired, or non-SCIM token
403	SCIM 2.0 error response	SCIM is disabled
409	SCIM 2.0 error response	A SCIM user with the same `userName` already exists
413	SCIM 2.0 error response	Request body too large
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while creating the user

Request body

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

Key path	Type	Default	Description
`schemas[]`	array		Include `"urn:ietf:params:scim:schemas:core:2.0:User"`.
`userName`	string		The SCIM user name. HCP Terraform preserves the provided casing but enforces uniqueness case-insensitively.
`externalId`	string		Optional identity-provider identifier for the user.
`displayName`	string		The user's human-readable name. HCP Terraform presents `displayName` value in the UI.
`emails[]`	array		Include at least one email object. HCP Terraform uses either the entry marked `primary=true` or the first entry if none is marked primary.
`emails[].value`	string		The user's email address.
`emails[].primary`	bool		Marks the primary email entry.
`active`	bool	`true`	When `false`, HCP Terraform creates the user in a suspended state.
`name.givenName`	string		Optional SCIM name field accepted from identity providers. HCP Terraform does not persist SCIM name fields.
`name.familyName`	string		Optional SCIM name field accepted from identity providers. HCP Terraform does not persist SCIM name fields.

Sample request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "user@example.com",
    "externalId": "ext-999",
    "emails": [
      {
        "value": "user@example.com",
        "primary": true
      }
    ],
    "active": true
  }' \
  "https://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/Users"

Sample response

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
    "userName": "user@example.com",
    "externalId": "ext-999",
  "displayName": "Firstname Lastname",
    "name": {
        "formatted": "user"
    },
    "emails": [
        {
            "value": "user@example.com",
            "primary": true
        }
    ],
    "active": true,
    "meta": {
        "resourceType": "User",
        "created": "2026-01-15T10:30:00Z",
        "lastModified": "2026-01-15T10:30:00Z"
    }
}

Replace a SCIM user

The following endpoint replaces the SCIM-managed attributes for an existing user. Include the full SCIM User resource body. HCP Terraform requires email data on replace requests.

PUT /scim/v2/:scim_configuration_id/Users/:id

If the PUT request targets a user who is not scoped to the current organization, such as a user who was provisioned by a different organization's SCIM configuration HCP Terraform rejects the request with an error rather than allowing a cross-organization mutation.

Path parameters

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

Status	Response	Reason
200	SCIM 2.0 user resource	Successfully replaced the user
400	SCIM 2.0 error response	Malformed JSON or missing email data
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	User not found
409	SCIM 2.0 error response	A conflicting `userName` already exists
413	SCIM 2.0 error response	Request body too large
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while replacing the user

Request body

This endpoint accepts a full SCIM User resource body.

Key path	Type	Description
`schemas[]`	array	Include `"urn:ietf:params:scim:schemas:core:2.0:User"`.
`userName`	string	The SCIM user name. HCP Terraform preserves the provided casing but enforces uniqueness case-insensitively.
`externalId`	string	Optional identity-provider identifier for the user.
`displayName`	string	The user's human-readable name. HCP Terraform presents `displayName` value in the UI.
`emails[]`	array	Include at least one email object. HCP Terraform uses either the entry marked `primary=true` or the first entry if none is marked primary.
`emails[].value`	string	The user's email address.
`emails[].primary`	bool	Marks the primary email entry.
`active`	bool	When `false`, HCP Terraform suspends the user. When omitted, HCP Terraform leaves the current suspension state unchanged.
`name.givenName`	string	Optional SCIM name field accepted from identity providers. HCP Terraform does not persist SCIM name fields.
`name.familyName`	string	Optional SCIM name field accepted from identity providers. HCP Terraform does not persist SCIM name fields.

Sample request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data '{
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "user@example.com",
    "externalId": "ext-1000",
    "emails": [
      {
        "value": "user@example.com",
        "primary": true
      }
    ],
    "active": true
  }' \
  "https://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/Users/52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126"

Sample response

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
    "externalId": "ext-1000",
  "displayName": "Firstname Lastname",
    "userName": "user@example.com",
    "name": {
        "formatted": "user"
    },
    "emails": [
        {
            "value": "user@example.com",
            "primary": true
        }
    ],
    "active": true,
    "meta": {
        "resourceType": "User",
        "created": "2026-01-15T10:30:00Z",
        "lastModified": "2026-01-15T11:00:00Z"
    }
}

Patch a SCIM user

The following endpoint partially updates a SCIM user with a SCIM PatchOp request body.

PATCH /scim/v2/:scim_configuration_id/Users/:id

If the PATCH request targets a user who is not scoped to the current organization, such as a user who was provisioned by a different organization's SCIM configuration HCP Terraform rejects the request with an error rather than allowing a cross-organization mutation.

Path parameters

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

Response codes

Status	Response	Reason
200	SCIM 2.0 user resource	Successfully updated the user
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
404	SCIM 2.0 error response	User not found
409	SCIM 2.0 error response	A conflicting `userName` already exists
413	SCIM 2.0 error response	Request body too large
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while updating the user

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	Target attribute path. Supported targeted paths are `active`, `userName`, `externalId`, and `emails`.
`Operations[].value`	mixed	The replacement value, added value, or bulk attribute object.

HCP Terraform supports the following PATCH operations:

replace on active, userName, externalId, and emails.
add on active, userName, externalId, and emails, which HCP Terraform treats the same as replace.
replace or add without a path where value is an object containing one or more supported attributes.
remove only for externalId.

HCP Terraform ignores attempts to clear required attributes such as userName, emails, or active.

Sample request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
      {
        "op": "Replace",
        "path": "active",
        "value": false
      }
    ]
  }' \
  "https://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/Users/52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126"

Sample response

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
    "externalId": "ext-999",
  "displayName": "Firstname Lastname",
    "userName": "user@example.com",
    "name": {
        "formatted": "user"
    },
    "emails": [
        {
            "value": "user@example.com",
            "primary": true
        }
    ],
    "active": false,
    "meta": {
        "resourceType": "User",
        "created": "2026-01-15T10:30:00Z",
        "lastModified": "2026-01-15T11:00:00Z"
    }
}

Delete a SCIM user

The following endpoint deprovisions a SCIM user. HCP Terraform removes the user's organization membership and SCIM identity. The underlying user account is preserved, as it may belong to other organizations.

DELETE /scim/v2/:scim_configuration_id/Users/:id

Refer to SCIM user lifecycle for more information.

Path parameters

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

Response codes

Status	Response	Reason
204	No content	Successfully deprovisioned the user
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	User not found
429	SCIM 2.0 error response	Rate limit exceeded
500	SCIM 2.0 error response	Internal error while deleting the user

Sample request

$ curl \
  --header "Authorization: Bearer $SCIM_TOKEN" \
  --request DELETE \
  "https://app.terraform.io/scim/v2/$SCIM_CONFIGURATION_ID/Users/52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126"

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 user resource.

Attribute	Type	Description
`schemas[]`	array	Always includes `"urn:ietf:params:scim:schemas:core:2.0:User"`.
`id`	string	The SCIM user ID returned by HCP Terraform.
`externalId`	string	The identity-provider identifier stored for the user.
`userName`	string	The SCIM user name stored for the user.
`name.formatted`	string	The HCP Terraform username associated with the user.
`emails[]`	array	The user's primary email information.
`emails[].value`	string	The stored email address for the user.
`emails[].primary`	bool	Always `true` for the returned primary email entry.
`active`	bool	`true` when the user is active and `false` when the user is suspended.
`meta.resourceType`	string	Always `"User"`.
`meta.created`	timestamp	The time the SCIM identity was created.
`meta.lastModified`	timestamp	The time the SCIM identity was last updated.

Sample SCIM user resource

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "52f5ecb9-59db-4f8d-9c9b-c2ec9a39e126",
    "externalId": "ext-999",
    "userName": "user@example.com",
    "name": {
        "formatted": "user"
    },
    "emails": [
        {
            "value": "user@example.com",
            "primary": true
        }
    ],
    "active": true,
    "meta": {
        "resourceType": "User",
        "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.