Setting up SCIM

Learn how to set up SCIM to use it with Sunlight!

Chelsea Ordoñez avatar
Written by Chelsea Ordoñez
Updated over a week ago

SCIM, which stands for System for Cross-domain Identity Management, is a very useful standard method that helps you connect all your systems together.

The goal of this is to help you manage or edit your employees’ information, as well as to add or remove them, in just one place. This way, all changes will be reflected in your company’s internal system and in an external system like Sunlight.

What are the benefits of integrating this with Sunlight?

The basics that SCIM will cover are the synchronization of users’ names and emails, and the addition or removal of users on Sunlight.

There are additional configurations concerning:

  • Cohorts: which involves the addition to or the removal of members from cohorts.

  • Managers: which involves the automatic creation of cohorts type manager and the addition to or the removal of a user from that cohort. Please notice that with this configuration, a user can only have one manager.

  • Budgets: which involves the addition of a prorated default budget to a new user based on the employee’s start date.

Technical Information

To begin with, we support SCIM 1.1 and SCIM 2.0.

Concerning the additional synchronization options previously mentioned (cohorts, managers and budgets), they can be achieved using SCIM enterprise extensions or custom schemas; however, since each company has a very particular organization structure, those configurations need to be discussed further in order to have them included in the integration.

An example of a partial user representation for syncing cohorts, managers and budgets is shown in the following snippet:

"urn:ietf:params:scim:schemas:extension:sunlight:2.0:User": {

"startDate": "2020-05-15"


"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

"manager": {

"value": "directory_usr_12345"


"organization": "Sunlight UK",

"division": "IT",

"department": "Development"


In the example above, we use the Enterprise extension and a custom schema. In this case, we would map the organization key with a Cohort Type and Sunlight UK with a Cohort belonging to that type. It’d be the same with division: IT and department: Development.

So, the user synced by this JSON representation would be assigned to those cohorts (and removed from any other they might belong to). Additionally, the manager directory_usr_12345 would be assigned to the user.

Regarding budgets, we’d use startDate for calculating the amount to be assigned when provisioning the user, based on a default budget and the days remaining of the year.

As mentioned above, given each company is unique, this configuration should be adapted based on your needs.

How can I proceed with this?

First of all, you’d need to reach out to our Support team, via email at or via chat, and inform them that your company wishes to integrate SCIM with Sunlight.

Afterwards, we’ll put you in contact with one of our developers to understand better what is needed from this integration so that it makes your life simpler!

Next, our development team will provide you with a URL and all the necessary instructions to start with the configuration. Then, when this is completed, our team will make sure that everything is working perfectly.

Finally, as soon as everything is tested and confirmed, you’ll have SCIM set up and be good to go!

Important notice:

  • Please take into account that in order to proceed with SCIM, your company must work with a SCIM provider, for example: Okta or iDaptive.

  • Please take into consideration that there is a third-party service provider involved in this integration: workOS. Meaning that all information that is being synchronized will go through them as well.

Have any questions or comments?

Please do not hesitate to contact our support team via our live chat or by emailing us at

Did this answer your question?