Manage SCIM tokens

Your identity provider (IdP) uses a SCIM token to connect to HelpDocs. Each token belongs to one HelpDocs account. See Provision users with SCIM first.

You need permission to edit settings to manage tokens. You'll find them in Settings > Sign-in & access, in the SCIM provisioning section.

About tokens

Your account can have up to 5 tokens. Use one for each IdP, or one for testing and one for production.
You see a token only once, when you create or rotate it. HelpDocs stores a scrambled copy and can't show it to you again.
Tokens start with hd_scim_, so they're easy to spot if one leaks.
Creating, rotating, and revoking a token is recorded in your Audit log.
Changes your IdP makes with a token show in your Audit log as SCIM: <token name>.

Creating your first token switches SCIM on. From then on:

SSO and Slack sign-in stop creating new members, and SSO sign-in stops changing members' roles and groups. See How SCIM changes SSO sign-in.
HelpDocs refuses manual changes to the members and groups your IdP manages. See Members are managed by your IdP.

Create a token

Go to Settings > Sign-in & access.

In the SCIM provisioning section, select Create token.

Enter a Name, up to 100 characters. Name it after the IdP that will use it.

Select Create token.

In Copy your SCIM token, select Copy, then paste the token into your IdP.

Select Done.

Once you close Copy your SCIM token, you can't see the token again. If you lose it, rotate it.

When you have 5 tokens, Create token is turned off. Revoke a token to create another.

See when a token was last used

The token list shows each token's Name, when it was Created, and when it was Last used. Hover over a Last used time to see the exact date. Never means the token hasn't been used yet.

Last sync shows the most recent time any token was used.

Last used updates at most once a minute.

Rotate a token

Rotating gives a token a new secret. Its name stays the same.

Select Rotate next to the token.

In Rotate <name>?, select Rotate.

Copy the new token and paste it into your IdP.

Select Done.

The old token stops working straight away. Your IdP can't sync until you paste in the new one.

Rotate without a gap

To switch tokens without your IdP losing its connection, create the new token before you revoke the old one.

Create a second token.

Paste it into your IdP.

Check that Last used updates for the new token.

Revoke the old token.

Revoke a token

Select Revoke next to the token.

In Revoke <name>?, select Revoke.

HelpDocs shows Token revoked. Your IdP can't sync with that token any more.

You can't undo revoking a token.

If you revoke your last token, SSO and Slack sign-in go back to creating new members, and SSO sign-in goes back to updating their roles and groups. Your members, and the groups your IdP pushed, stay as they are, and you can edit them in HelpDocs again.

If a token leaks

Rotate or revoke the token straight away.

Check your Audit log for changes made as SCIM: <token name>.