scim-configuration API reference

This topic provides reference information for the /scim-configuration endpoints. The SCIM configuration controls whether HCP Terraform accepts SCIM provisioning requests from your identity provider for an organization.

Each organization has at most one SCIM configuration. The configuration's external ID is the :scim_configuration_id path segment in the SCIM provisioning endpoints. Refer to the SCIM API for details about those endpoints.

Only members of the owners team or an owners team API token can access these endpoints.

Show a SCIM configuration

GET /organizations/:organization_name/scim-configuration

This endpoint returns the SCIM configuration for an organization.

Path parameters

Parameter	Description
`:organization_name`	The name of the organization to read SCIM configuration settings from.

Response codes

Status	Response	Reason
200	JSON API document (`type: "scim-configurations"`)	Successfully returned the SCIM configuration
404	JSON API error object	Organization or SCIM configuration not found or user unauthorized to perform action

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  https://app.terraform.io/api/v2/organizations/my-scim-org/scim-configuration

Sample response

{
  "data": {
    "id": "scimconf-vaRz2K9cXJzARfrgzcVrDyCYJyap8b",
    "type": "scim-configurations",
    "attributes": {
      "created-at": "2026-01-09T19:48:58.268Z",
      "updated-at": "2026-01-09T19:48:58.268Z",
      "enabled": true
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-scim-org",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-scim-org/scim-configuration",
      "enable": "/api/v2/organizations/my-scim-org/scim-configuration/actions/enable",
      "disable": "/api/v2/organizations/my-scim-org/scim-configuration/actions/disable"
    }
  }
}

Create a SCIM configuration

POST /organizations/:organization_name/scim-configuration

This endpoint creates the SCIM configuration for an organization. The organization must have SSO configured in order to create a configuration.

Path parameters

Parameter	Description
`:organization_name`	The name of the organization to configure SCIM for.

Response codes

Status	Response	Reason
201	JSON API document (`type: "scim-configurations"`)	Successfully created the SCIM configuration
404	JSON API error object	Organization not found or user unauthorized to perform action
422	JSON API error object	SSO is not configured or the organization already has a SCIM configuration

Request body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"scim-configurations"`.
`data.attributes.enabled`	bool	`true`	Whether HCP Terraform accepts requests to sync users and groups from your identity provider.

Sample payload

{
  "data": {
    "type": "scim-configurations",
    "attributes": {
      "enabled": true
    }
  }
}

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/my-scim-org/scim-configuration

Sample response

{
  "data": {
    "id": "scimconf-vaRz2K9cXJzARfrgzcVrDyCYJyap8b",
    "type": "scim-configurations",
    "attributes": {
      "created-at": "2026-01-09T19:48:58.268Z",
      "updated-at": "2026-01-09T19:48:58.268Z",
      "enabled": true
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-scim-org",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-scim-org/scim-configuration",
      "enable": "/api/v2/organizations/my-scim-org/scim-configuration/actions/enable",
      "disable": "/api/v2/organizations/my-scim-org/scim-configuration/actions/disable"
    }
  }
}

Enable SCIM

PUT /organizations/:organization_name/scim-configuration/actions/enable

This endpoint sets enabled to true on the organization's SCIM configuration.

Path parameters

Parameter	Description
`:organization_name`	The name of the organization to enable SCIM for.

Response codes

Status	Response	Reason
200	JSON API document (`type: "scim-configurations"`)	Successfully enabled SCIM
404	JSON API error object	Organization or SCIM configuration not found or user unauthorized to perform action

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PUT \
  https://app.terraform.io/api/v2/organizations/my-scim-org/scim-configuration/actions/enable

Sample response

A successful request returns the SCIM configuration with enabled set to true.

{
  "data": {
    "id": "scimconf-vaRz2K9cXJzARfrgzcVrDyCYJyap8b",
    "type": "scim-configurations",
    "attributes": {
      "created-at": "2026-01-09T19:48:58.268Z",
      "updated-at": "2026-01-14T17:02:11.914Z",
      "enabled": true
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-scim-org",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-scim-org/scim-configuration",
      "enable": "/api/v2/organizations/my-scim-org/scim-configuration/actions/enable",
      "disable": "/api/v2/organizations/my-scim-org/scim-configuration/actions/disable"
    }
  }
}

Disable SCIM

PUT /organizations/:organization_name/scim-configuration/actions/disable

This endpoint sets enabled to false on the organization's SCIM configuration, which temporarily pauses SCIM provisioning. Requests to the SCIM provisioning endpoints for the organization return an error while SCIM is disabled. Refer to Manage SCIM provisioning for more information.

Path parameters

Parameter	Description
`:organization_name`	The name of the organization to disable SCIM for.

Response codes

Status	Response	Reason
200	JSON API document (`type: "scim-configurations"`)	Successfully disabled SCIM
404	JSON API error object	Organization or SCIM configuration not found or user unauthorized to perform action

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PUT \
  https://app.terraform.io/api/v2/organizations/my-scim-org/scim-configuration/actions/disable

Sample response

A successful request returns the SCIM configuration with enabled set to false.

{
  "data": {
    "id": "scimconf-vaRz2K9cXJzARfrgzcVrDyCYJyap8b",
    "type": "scim-configurations",
    "attributes": {
      "created-at": "2026-01-09T19:48:58.268Z",
      "updated-at": "2026-01-14T17:02:11.914Z",
      "enabled": false
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-scim-org",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-scim-org/scim-configuration",
      "enable": "/api/v2/organizations/my-scim-org/scim-configuration/actions/enable",
      "disable": "/api/v2/organizations/my-scim-org/scim-configuration/actions/disable"
    }
  }
}

Delete a SCIM configuration

DELETE /organizations/:organization_name/scim-configuration

This endpoint deletes the SCIM configuration for an organization. You must disable SCIM before you delete the configuration.

Deleting the configuration also deletes the organization's SCIM tokens and the SCIM records for provisioned users and teams. HCP Terraform does not delete the users and teams themselves.

Path parameters

Parameter	Description
`:organization_name`	The name of the organization to delete the SCIM configuration from.

Response codes

Status	Response	Reason
204	Empty response	Successfully deleted the SCIM configuration
404	JSON API error object	Organization or SCIM configuration not found or user unauthorized to perform action
409	JSON API error object	SCIM is still enabled for the organization

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --request DELETE \
  https://app.terraform.io/api/v2/organizations/my-scim-org/scim-configuration

Sample response

A successful request returns a 204 No Content response with no body.