SCIM or the System for Cross-domain Identity Management specification is a standard protocol to manage accounts across multiple services: add teammates, change their properties, such as name, or disable accounts to revoke access.
Integrating Intercom with your identity provider makes managing teammates simple and secure.
Before you start
Important: There are several prerequisites for setting up SCIM:
Before setting up SCIM, SAML SSO must be set up and enabled in your workspace.
SCIM Provisioning is only available with certain Intercom plans. Check our plans and pricing to add this to your subscription.
Each Intercom workspace you want to provision to must be set up as a separate app in your Identity Provider.
How to enable SCIM
Make sure SAML SSO is enabled.
Then open Provisioning and select Enable SCIM provisioning.
A Base URL and API Token will become available after you save the security settings.
Copy the Base URL and API Token and add them to the configuration of the Intercom app in your Identity Provider (e.g., Okta, OneLogin, Azure ActiveDirectory).
Configuring provisioning settings
After enabling SCIM, you must configure how new teammates are provisioned and how departing teammates are deprovisioned.
Set default teammate permissions
When a new teammate is created by your identity provider, Intercom gives them a default set of permissions.
Make sure SAML SSO is enabled.
Open the Provisioning section.
Under "Default teammate permissions" click Edit.
Toggle on the permissions new teammates should have when they are provisioned.
Configure deprovisioning settings
When teammates are deprovisioned by your IdP, their account will be deleted from Intercom. This setting controls who their assigned items (conversations, articles, etc.) are reassigned to.
Make sure SAML SSO is enabled.
Open the Provisioning section.
In the Deprovisioning section, you can choose who should get ownership of each type of data.
If you choose the Default option, Intercom will assign items to the first teammate in the workspace. These can be reassigned later.
You can also choose specific teammates to be excluded from deprovisioning. This can help your IT Team keep access to your Intercom workspace in case of a misconfiguration or emergency.
How SCIM manages teammates
Once configured, your IdP will manage your teammates in Intercom.
Creating teammates
This is the typical user provisioning flow:
The IT Team adds a new teammate to the company's Identity Provider directory.
The IT Team assigns the Intercom app to the new teammate on the IdP's platform.
The IdP sends an HTTP request to Intercom, which creates a new teammate in the Intercom workspace.
The new teammate is automatically given the permissions you configured under Default teammate permissions.
Note: If an admin account with the same email already exists in Intercom, SCIM will grant this existing account access to the customer's workspace.
Updating teammates
When your IT Team changes a teammate’s name in the IdP's directory, the IdP sends an HTTP request to Intercom to update the teammate’s name in Intercom.
Deleting teammates
This is the typical user SCIM Deprovisioning Settings.
The IT Team removes the Intercom app assignment from a teammate in the IdP.
The IdP sends an HTTP request to Intercom to remove the teammate from the workspace.
Intercom automatically reassigns all objects (conversations, outbound messages, contacts, articles) assigned to that teammate according to your Deprovisioning teammates settings.
Important deactivation warning: Teammates in Intercom today can be in one of two states: "active" or "deleted". Intercom does not support any soft-deleted, de-activated, or archived state for teammates.
When a teammate is not active in your identity provider, their account will be permanently deleted from the Intercom workspace. If the teammate has access to any other workspaces, that access is retained.
Managing teammate permissions via SCIM
You can push your identity provider groups to Intercom and map those groups to specific teammate roles. See our article on assigning teammate roles via SCIM groups for more details.
Limitations and important notes
Known limitations
Our current SCIM implementation doesn’t support:
Adding a teammate to a team or removing them from a team
Assigning or removing seats for teammates
Giving a default role on provisioning (this must be done via SCIM group mapping)
Giving default seats on provisioning
Important notes
Note:
Intercom's provisioning capability is built using version 2.0 of the SCIM protocol.
Intercom considers email addresses to be case insensitive (e.g., "Teammate@example.com" is the same as "teammate@example.com").
If a "displayName" parameter is sent in the request, it will be used instead of the "name" parameter.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts