Manage SCIM Tokens

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

Overview

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

SCIM tokens have the following characteristics:

Tokens are valid only for /scim/v2/* endpoints. They cannot access other HCP Terraform APIs.

Tokens have a mandatory expiration date that you must set at creation. You can set the expiration between 30 days and one year from the creation date.
You can create multiple active tokens simultaneously. This enables zero-downtime token rotation. Refer to Rotate a token for guidance on minimizing interruption.

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. The token value is displayed only once at creation time and cannot be retrieved afterward.
Created at	The timestamp when the token was created.
Expired at	The timestamp when the token expires. Expiration is mandatory and must be set between 30 days and one year at creation time.
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 members of the owners team can create, view, and revoke SCIM tokens.

Before using SCIM tokens for provisioning, enable SCIM. Refer to Configure SCIM provisioning for instructions.

Create a SCIM token

Token creation is part of the initial SCIM setup flow in HCP Terraform. Refer to the Enable SCIM section of the configure guide for instructions. To replace an expired or lost token, refer to Rotate a token.

List tokens

You can view existing active SCIM tokens on the SCIM provisioning page. You can access the page from your organization settings.

Use the Last used timestamp to identify which tokens are actively in use by your identity provider. HCP Terraform 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:

Navigate to your organization settings, then click SCIM provisioning
In the row containing the token you want to delete, click the trash icon in the Actions column of the tokens table.
When prompted, enter delete in the dialog, then click Delete to continue.

Rotate a token

To rotate a SCIM token:

Generate a new token by following the steps in Enable SCIM. Set a new expiration date between 30 days and one year.
Update your identity provider with the new token value.
Verify the new token works by checking that SCIM provisioning operations succeed.
Delete the old token after confirming the new token is working.

Expired token status

No alerts are sent before a SCIM token expires. The expiration status for each token is visible on the SCIM provisioning.

When an expired token causes 401 Unauthorized errors, refer to Troubleshoot SCIM provisioning for recovery steps.

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.

Set a calendar reminder one to two weeks before your token expires. Tokens have a mandatory expiration of 30 days to one year and no expiration alerts are sent.
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 SCIM tokens API reference for more information.