System for Cross-domain Identity Management (SCIM) for Insomnia

Use SCIM (System for Cross-domain Identity Management) to manage users and teams in Insomnia through your identity provider (IdP) instead of managing them manually.

SCIM is available on the Enterprise plan and is designed to work alongside Single Sign-On (SSO). In Insomnia, SCIM provisioning is one-way. When you enable SCIM, Insomnia uses your IdP as the source of truth for provisioning. This means that you can:

• Provision Enterprise users and teams from your IdP.
• Manage user access, team membership, and license consumption through your IdP after configuring SSO.
• Keep existing manually managed users unchanged unless you explicitly modify them.

Insomnia supports SCIM provisioning with the following identity providers:

• Okta
• Azure

When you enable SCIM in Insomnia, use your IdP to manage SCIM-managed users and teams.

Before enabling SCIM, you must meet all of the following requirements in Insomnia:

• Your organization is on the Enterprise plan.
• You are an Owner or Co-Owner in the Insomnia organization.
• You have verified at least one domain in Insomnia.
• You configured SSO for your identity provider.

In your IdP, you must:

• Have an administrator account
• Have permission to configure SCIM provisioning for the Insomnia application
• Configure SSO between your IdP and Insomnia.

SCIM provisioning in Insomnia follows predictable, non-destructive rules:

• Users and teams that you assigned to the Insomnia application in your IdP are provisioned by Insomnia.
• Insomnia matches existing Insomnia users to IdP users by email address.
• If a user exists in Insomnia but not in the IdP, Insomnia doesn’t remove or disable that user automatically.

SCIM provisioning lets you manage access to Insomnia through your IdP, in the same way that you manage access to other enterprise applications.

SCIM applies only to users and groups provisioned through your identity provider. Users who were added manually before SCIM was enabled remain unchanged and continue to consume licenses until you update or remove them manually. Insomnia does not automatically reconcile or modify manually added users when you enable SCIM. This behavior prevents unintended changes to existing accounts.

User lifecycle behavior

When you assign a user to the Insomnia application in your IdP, the IdP provisions that user in Insomnia through SCIM.

• If the user doesn’t exist in Insomnia, Insomnia creates the user.
• If the user already exists in Insomnia, Insomnia matches the user by email address.

When you unassign, deactivate, or delete a user in your IdP, the IdP sends a provisioning update to Insomnia.

When SCIM is enabled, the following users consume Insomnia licenses:

• Users provisioned through SCIM consume Enterprise licenses.
• Manually added users continue to consume licenses until you remove them or transition them to IdP-managed provisioning.

For more information about license management, see Enterprise user management.

SCIM provisioning uses a connector URL and token generated in Insomnia. The token authorizes your identity provider to provision users and teams.

Administrators can view the current SCIM token status in Insomnia:

1. From the Insomnia Enterprise control dashboard sidebar, click SCIM.
2. Review the SCIM configuration page to see:
   • If SCIM is enabled.
   • If the token is valid, expiring soon, or expired.

When a token is close to expiration and cannot be refreshed automatically, Insomnia displays a warning message on the SCIM page and sends email notifications starting 20 days before the token expires.

Connector URL and token

SCIM provisioning uses a connector URL and token generated in Insomnia. The token authorizes your IdP to provision users and teams. When you enable SCIM in Insomnia from the Enterprise Controls, a modal opens for you to generate the token.

The token is displayed only once when it is generated. Store it securely. If you lose the token, refresh it in Insomnia and update the token in your IdP. To manually refresh the SCIM token, navigate to SCIM.

Automatic token refresh

When generating the token, you can choose an expiration window. Available options include 30 days, 90 days, 180 days, 1 year, 2 years, or no expiration.

The token is displayed only once when it is generated. Store it securely. If you lose the token, refresh it in Insomnia and update the token in your IdP. To manually refresh the SCIM token, navigate to SCIM.

Automatic token refresh

SCIM tokens expire based on the expiration window selected when the token is generated in Insomnia.

If the token expires and is not renewed:

• New users aren’t provisioned from the identity provider.
• Users that you deactivate in the identity provider aren’t removed from Insomnia.
• SCIM provisioning stops until the token is refreshed.

You must manually refresh the token from the SCIM settings:

1. In the Insomnia web app, navigate to Enterprise Controls > SCIM.
2. Select Refresh Token.
3. Enter your passphrase to generate a new token.
4. In your identity provider, update the token.

Use SCIM logs to validate your SCIM configuration and troubleshoot provisioning issues. To view SCIM request logs, navigate to Enterprise Controls > SCIM.

Now that you understand how SCIM works in Insomnia and have confirmed the requirements, configure SCIM with your identity provider.

Follow one of the provider-specific guides:

• Configure SCIM for Insomnia with Okta
• Configure SCIM for Insomnia with Azure