Admin SCIM Tokens API

This topic provides reference information for the /admin/scim-tokens endpoint, which manages SCIM (System for Cross-domain Identity Management) authentication tokens for Terraform Enterprise.

Use SCIM tokens to authenticate requests from your identity provider (IdP) to Terraform Enterprise's SCIM endpoints. These tokens enable automated user and group provisioning from identity providers such as Okta and Microsoft Entra ID. Terraform Enterprise only accepts these tokens for SCIM provisioning requests while SCIM is enabled on the instance. Use the SCIM Settings API to enable or disable SCIM provisioning for the instance.

Only site administrators can list, inspect, create, and delete SCIM tokens. Request and response documents use the JSON:API resource type authentication-tokens.

Token attributes

The following attributes are available for SCIM tokens:

List SCIM tokens

GET /api/v2/admin/scim-tokens

This endpoint returns a list of SCIM tokens. The response includes metadata about each token. For existing tokens, the token attribute is null. Terraform Enterprise only returns the secret value when you create a token.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/admin/scim-tokens

Sample Response

{
    "data": [
        {
            "id": "at-7nXaJmPbCLks9Q2R",
            "type": "authentication-tokens",
            "attributes": {
                "description": "Okta SCIM Integration",
                "token": null,
                "created-at": "2026-01-15T10:30:00Z",
                "expired-at": "2027-01-15T10:30:00Z",
                "last-used-at": "2026-02-01T14:22:35Z"
            }
        },
        {
            "id": "at-9mYbKnQdDMlt4H8P",
            "type": "authentication-tokens",
            "attributes": {
                "description": "Azure Entra ID Integration",
                "token": null,
                "created-at": "2026-01-20T08:15:00Z",
                "expired-at": "2027-01-20T08:15:00Z",
                "last-used-at": null
            }
        }
    ]
}

Show a SCIM token

GET /api/v2/admin/scim-tokens/:token_id

This endpoint returns metadata for a single SCIM token. For existing tokens, the token attribute is null. Terraform Enterprise only returns the secret value when you create a token.

Parameters

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/admin/scim-tokens/at-7nXaJmPbCLks9Q2R

Sample Response

{
    "data": {
        "id": "at-7nXaJmPbCLks9Q2R",
        "type": "authentication-tokens",
        "attributes": {
            "description": "Okta SCIM Integration",
            "token": null,
            "created-at": "2026-01-15T10:30:00Z",
            "expired-at": "2027-01-15T10:30:00Z",
            "last-used-at": "2026-02-01T14:22:35Z"
        }
    }
}

Create a SCIM token

POST /api/v2/admin/scim-tokens

This endpoint creates a new SCIM token. The response includes the secret token value. Store this value in a secure location, because you cannot retrieve it later. If you lose it, create a new token.

Request Body

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

Sample Payload

{
    "data": {
        "type": "authentication-tokens",
        "attributes": {
            "description": "Okta SCIM Integration",
            "expired-at": "2027-01-15T10:30:00Z"
        }
    }
}

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://tfe.example.com/api/v2/admin/scim-tokens

Sample Response

{
    "data": {
        "id": "at-7nXaJmPbCLks9Q2R",
        "type": "authentication-tokens",
        "attributes": {
            "description": "Okta SCIM Integration",
            "token": "scim-example-token-value-redacted-format",
            "created-at": "2026-01-15T10:30:00Z",
            "expired-at": "2027-01-15T10:30:00Z",
            "last-used-at": null
        }
    }
}

Delete a SCIM token

DELETE /api/v2/admin/scim-tokens/:token_id

This endpoint deletes a SCIM token. Once deleted, any identity provider configured with this token can no longer authenticate with Terraform Enterprise's SCIM endpoints.

To rotate a token without disrupting provisioning, refer to Token rotation.

Parameters

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://tfe.example.com/api/v2/admin/scim-tokens/at-7nXaJmPbCLks9Q2R

Token rotation

To rotate a SCIM token without disrupting provisioning, complete the following steps:

1. Create a new token using the Create a SCIM token endpoint.
2. Update your identity provider configuration with the new token value.
3. Verify that provisioning operations are working correctly with the new token.
4. Delete the old token using the Delete a SCIM token endpoint.

Because multiple tokens can be active simultaneously, this process enables zero-downtime rotation.