Manage SCIM Tokens

This topic describes how to generate, rotate, and delete SCIM tokens in Terraform Enterprise. Your identity provider (IdP) uses SCIM tokens to authenticate with Terraform Enterprise when provisioning users and groups.

Overview

SCIM tokens are bearer tokens that authenticate your identity provider when it communicates with Terraform Enterprise's SCIM endpoints. The IdP includes the token in the Authorization header of each SCIM API request.

SCIM tokens have the following characteristics:

Scope: Tokens are valid only for SCIM endpoints (/scim/v2/*). They cannot access other Terraform Enterprise APIs.
Expiration: Tokens created through the API default to 365 days when no expiration is specified. You can configure token expiration up to 12 months.
Multiple tokens: You can create multiple active tokens simultaneously. This enables zero-downtime token rotation. Refer to the Public SCIM API for public SCIM rate-limit behavior.

Token properties

Each SCIM token has the following properties:

Property	Description
Description	A human-readable label to help identify the token's purpose.
Token value	The secret bearer token value. Terraform Enterprise stores tokens as one-way hashes using HMAC-SHA512, so the original value cannot be retrieved. Terraform Enterprise only displays this value once at creation time.
Created at	The timestamp when the token was created.
Expired at	The timestamp when the token expires. Tokens created through the API default to 365 days if no expiration is specified.
Last used at	The timestamp when the token was last used for a SCIM API request. Updated with a 1-minute throttle to reduce database writes.

Requirements

Only site administrators can create, view, and revoke SCIM tokens. For more information about site admin permissions, refer to Site Administration Permissions.

Before using SCIM tokens for provisioning, enable SCIM. Terraform Enterprise only accepts SCIM token-authenticated provisioning requests while SCIM is enabled. Refer to Configure SCIM provisioning for instructions.

Create a SCIM token

To create a new SCIM token:

Open your user icon menu and click Site Admin.
Click SCIM in the left navigation.
In the SCIM Tokens section, click Create Token.
Enter a Description for the token, for example IdP name or environment.
Optionally, set the token expiration. You can choose one of the following presets: 30-day, 90-day, or 365-day.
Click Create Token.
Copy the token value and store it securely. You will not be able to retrieve it again.

Terraform Enterprise stores tokens as one-way hashes using HMAC-SHA512. As a result, the original token value cannot be retrieved after creation. If you lose the token, you must create a new one.

After creating the token, configure your identity provider to use this token for SCIM provisioning. Refer to the IdP-specific configuration guides:

Note that Terraform Enterprise blocks SCIM token creation while you are impersonating another user. Refer to Impersonating a User for more information.

List tokens

You can view all SCIM tokens from the SCIM settings page:

Open your user icon menu and click Site Admin.
Click SCIM in the left navigation.
View the list of tokens in the SCIM Tokens section.

The token list displays metadata for each token, including the description, creation date, expiration date, and last used timestamp. The list does not display the secret token values.

Use the Last used at timestamp to identify which tokens are actively in use by your identity provider. Terraform Enterprise updates this value with a 1-minute throttle, so recent requests may not appear immediately.

Delete a token

Deleting a SCIM token revokes access. Revoking a token immediately invalidates it, and any SCIM requests using that token fail with an HTTP 401 Unauthorized error. You can delete a token at any time.

Warning

Revoking a token is immediate and irreversible. If your identity provider is actively using the token, SCIM requests authenticated with that token begin failing until you update the IdP with a new token.

To delete a token:

Open your user icon menu and click Site Admin.
Click SCIM in the left navigation.
In the SCIM Tokens section, locate the token you want to delete.
Click the delete icon next to the token.
Confirm the deletion.

Rotate a token

To rotate a SCIM token with zero downtime:

Generate a new token before the old token expires. Refer to Token properties for expiration details.
Update your identity provider with the new token value.
Verify the new token works by checking that SCIM provisioning operations succeed and the new token's Last used at timestamp updates.
Delete the old token after confirming the new token is working.

Terraform Enterprise supports multiple active tokens, so you can rotate tokens without interrupting SCIM provisioning.

Expired token status

Terraform Enterprise does not send alerts before a SCIM token expires. When a token has expired, Terraform Enterprise surfaces that status in the following places:

On the Site Admin > SCIM page, a page alert appears above the SCIM settings.
In the Site Admin navigation, a warning icon appears next to SCIM provisioning.

The token list shows an expiration badge for each token, including whether it is expired or when it will expire.

Rotate tokens before they expire to avoid downtime.

Best practices for managing tokens

Use descriptive names for tokens, such as IdP name, environment, and creation date.
Plan for rotation and set reminders before expiration.
Monitor token usage and remove unused tokens.
Limit token lifetime according to your security policy.
Store token values securely and never share them through insecure channels.

API reference

You can also manage SCIM tokens programmatically with the SCIM Tokens API. Refer to that page for list, create, and delete operations, request and response details, expiration fields, and rate limits.