SCIM Users API reference

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

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

List SCIM Users

GET /scim/v2/Users

This endpoint returns SCIM-managed users. Without a filter, Terraform Enterprise returns a paginated SCIM list response.

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

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 or paused
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://tfe.example.com/scim/v2/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

GET /scim/v2/Users/:id

This endpoint returns a single SCIM user resource.

Parameter	Description
`:id`	The SCIM user ID returned in the user's `id` field.

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 or paused
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://tfe.example.com/scim/v2/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

POST /scim/v2/Users

This endpoint provisions a new SCIM user. If Terraform Enterprise already has a manually managed user with the same email address, Terraform Enterprise links that existing user to the new SCIM identity instead of creating a duplicate user record.

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 or paused
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. Terraform Enterprise preserves the provided casing but enforces uniqueness case-insensitively.
`externalId`	string		Optional identity-provider identifier for the user.
`emails[]`	array		Include at least one email object. Terraform Enterprise 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`, Terraform Enterprise creates the user in a suspended state.
`name.givenName`	string		Optional SCIM name field accepted from identity providers. Terraform Enterprise does not persist SCIM name fields.
`name.familyName`	string		Optional SCIM name field accepted from identity providers. Terraform Enterprise 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://tfe.example.com/scim/v2/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",
    "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

PUT /scim/v2/Users/:id

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

Parameter	Description
`: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 or paused
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. Terraform Enterprise preserves the provided casing but enforces uniqueness case-insensitively.
`externalId`	string	Optional identity-provider identifier for the user.
`emails[]`	array	Include at least one email object. Terraform Enterprise 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`, Terraform Enterprise suspends the user. When omitted, Terraform Enterprise leaves the current suspension state unchanged.
`name.givenName`	string	Optional SCIM name field accepted from identity providers. Terraform Enterprise does not persist SCIM name fields.
`name.familyName`	string	Optional SCIM name field accepted from identity providers. Terraform Enterprise 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://tfe.example.com/scim/v2/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",
    "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

PATCH /scim/v2/Users/:id

This endpoint partially updates a SCIM user with a SCIM PatchOp request body.

Parameter	Description
`:id`	The SCIM user ID returned in the user's `id` field.

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 or paused
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.

Terraform Enterprise supports the following PATCH operations:

Replace on active, userName, externalId, and emails.
Add on active, userName, externalId, and emails, which Terraform Enterprise 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.

Terraform Enterprise 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://tfe.example.com/scim/v2/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": false,
    "meta": {
        "resourceType": "User",
        "created": "2026-01-15T10:30:00Z",
        "lastModified": "2026-01-15T11:00:00Z"
    }
}

Delete a SCIM User

DELETE /scim/v2/Users/:id

This endpoint deprovisions a SCIM user. Terraform Enterprise removes the SCIM identity, suspends the underlying Terraform Enterprise user record, and revokes SCIM-granted site administrator access if applicable.

Parameter	Description
`:id`	The SCIM user ID returned in the user's `id` field.

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 or paused
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

Response Attributes

Terraform Enterprise 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 Terraform Enterprise.
`externalId`	string	The identity-provider identifier stored for the user.
`userName`	string	The SCIM user name stored for the user.
`name.formatted`	string	The Terraform Enterprise 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 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.