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). 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

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.
• Existing Insomnia users are matched 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.

When SCIM is enabled, Insomnia licenses are consumed like the following:

• 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.

Automatic token refresh

Insomnia automatically attempts to refresh the SCIM connector token every 90 days, before it expires. This helps prevent provisioning interruptions that are caused by routine token expiration and reduces the need for manual maintenance. If the automatic refresh succeeds, SCIM provisioning continues without interruption.

Warning: If the automatic refresh fails, SCIM effectively breaks. Account owners must manually refresh the token to continue SCIM provisioning. Insomnia will warn the account owner and co-owners that the refresh failed. If the token isn’t refreshed after it expires, then the following happen:

• New users aren’t provisioned from the identity provider.
• Users deactivated in the identity provider aren’t removed from Insomnia.

If the token refresh fails, 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.

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