System for Cross-domain Identity Management (also known as SCIM) is a protocol for user management across multiple applications. It allows an IT or Operations team to easily provision (add), de-provision (deactivate), and update user data across multiple applications at once. 

 

Which SCIM capabilities are supported?

The following SCIM capabilities are supported in monday.com:

• Provisioning of Users
• De-provisioning of Users
• Provisioning of Teams
• De-provisioning of Teams
• Team Renaming
• Updating User Details
• Assigning Users to Teams
• Unassigning Users from Teams

 

SCIM Setup Options

There are three ways to set up SCIM Provisioning for your monday.com account:

1. Existing monday.com SCIM applications
   We currently work with three main providers: OKTA, Entra ID, and OneLogin. Aside from these, you also have the option to use your own provider (see the second option) or integrate directly with our SCIM API (see the third option).
   
   You can read more on enabling SCIM Provisioning for existing monday.com applications below:
   SCIM Provisioning using OKTA
   SCIM Provisioning using Entra ID
   SCIM Provisioning using OneLogin
   
   
2. Custom SCIM integration with identity providers
   You can learn all about Custom SCIM integration in this article.
   
   
3. SCIM API
   This method will be covered in the article below. Continue reading to learn more about setting up SCIM Provisioning using the API!

 

SCIM API

Our SCIM implementation targets version 2.0 of the protocol.

The base URL for all calls from the identity provider to monday.com is: https://<YOUR_DOMAIN>.monday.com/scim/v2/. All SCIM methods are branches of this base URL.

 

Bearer Token

An OAuth bearer token must be attached to every SCIM request. To generate a bearer token, open up the admin section of your account. From there, press on the "Security" tab, open up the SCIM section, click on the "Generate" button and copy the generated token.

 

 

The token must be included via an Authorization header with a type of Bearer when calling any of the SCIM methods.

Example of using the bearer token:

GET /scim/v2/Users
Host: company.monday.com
Accept: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIi2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt94Ux83XXXXXXXX

 

SCIM Endpoints

• User attributes

Attributes are a set of details about the user and the state of the user. Sometimes, multiple SCIM attributes map out to a single monday.com profile field. For example, monday.com's "Name" field will be populated by either "displayName" or the name SCIM attributes. 

 

The following table presents all user attributes supported in monday.com’s SCIM API:

monday.com Attribute	SCIM API Attribute(s)	Description	Example Value
Name (required)	name, displayName	The user's displayed name	"name": { "givenName": "Test", "familyName": "User" } "displayName": "Test User"
Email Address (required)	userName, email	The email address used by the user to log into monday.com	"userName": "employee@company.com" "emails": [{ "type": "work", "primary": true, "value": "employee@company.com" }]
Active (required)	active	When creating a user, this field must be set to 'true'. Changing a user's 'active' value to 'false' will deactivate them in the monday.com.	"active": true
Position	title	The user's position in the company.	"title": "Senior IT Engineer"
Timezone	timezone	The user's timezone, all dates in the platform will be according to this timezone. Both 'Europe/Berlin' and 'Berlin' formats are acceptable	"timezone": "Pacific Time (US & Canada)"
Locale	locale	monday.com will display a localized version for different locales.	"locale": "fr"
Phone Number	phoneNumbers	The user's phone numbers. Note: only one will be displayed, the one marked as 'primary' or otherwise the first number.	"phoneNumbers": [{ "value": "+972523090049", "type": "work", "primary": true }]
Home Address	addresses	The user's address. Only one address will be displayed, the one marked as 'primary' or otherwise the first address. Note: attribute is not supported in the PATCH /Users/{id} operation	"addresses": [{ "value": "21B Baker St., London", "type": "work", "primary: true }]
User Type	userType	The level of each user within the account (learn about it here).   The possible values are: admin member viewer guest or custom role id	"userType": "admin"

 

To set up SCIM provisioning to support custom roles as user types:

1. Configure the relevant custom role on monday.com as described in this article.
2. Copy the custom role ID. This can be done from the account permissions center, by clicking on the three-dot menu right next to the role name and then "Copy ID", as shown below.
3. When setting the userType please pass the custom role ID's as a "string"(the same way you would pass the value admin, viewer, member, or guest).

 

User Endpoints

• GET /Users

This returns a paginated list of users, default itemsPerPage is 50. You can use a filter to search users; you can only search by their email address and only the eq operator is supported. In order to search by an email address, you'd have to supply it as userName.

Below, you'll find an example of a paginated list of users request:

GET /scim/v2/Users?filter=userName eq employee@company.com&count=51&startIndex=4
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiwicGVyIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX

 

 

By default, querying the GET /Users endpoint, will only retrieve the users that have been SCIM provisioned on your account already. To retrieve all users, even those that have not been provisioned yet, you can add the below parameter onto your query:

GET /scim/v2/Users?scim_provisioned_only=false

To retrieve inactive users, you can add the below parameter onto your query:

GET /scim/v2/Users?include_inactive=true

 

• GET /Users/{id}

This retrieves a specific user matching the supplied SCIM ID. To find out a user's SCIM ID, you can send a GET request and filter for their userName.

Example:

GET /scim/v2/Users/80d60b37-3c75-4e41-9bb0-ae6588b6448d
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiwicGVyIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX

 

• POST /Users

This request creates a user in monday.com. It must include an email address, either in emails or userName fields, as well as the field active with the value set to true. Any other fields are optional.

1. if the user is deactivated, they will become activated
2. alternatively, if the user is active but was not provisioned previously, then they will become provisioned (meaning they will now have a scim_uid and will return when getting all users)

Otherwise, a 419 Conflict response will be returned. Successful requests are responded with 201 Created. 

Example:

POST /scim/v2/Users
Host: company.monday.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiwicGVyIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX


{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
   "userName": "employee@company.com",
   "name": {
       "givenName": "Test",
       "familyName": "User"
   },
   "emails": [{
       "primary": true,
       "value": "employee@company.com",
       "type": "work"
   }],
   "displayName": "Test User",
   "locale": "es",
   "timezone": "Europe/Brussels",
   "title": "Full-Stack Engineer",
   "addresses": [{
       "type": "work",
       "primary": true,
       "value": "21B Baker St., London"
   }],
   "externalId": "00ujl29u0le5T6Aj10h7",
   "active": true
}

 

• PATCH /Users/{id}

The patch request allows an update of a specific user’s attributes. Attributes that are not mentioned in this request will not be changed.

Example:

PATCH /scim/v2/Users/80d60b37-3c75-4e41-9bb0-ae6588b6448d
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiwicGVyIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX


{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
   "Operations": [{
       "op": "replace",
       "value": {
           "active": false
       }
   }]
}

• PUT /Users/{id}

The put request updates a user completely. It’s useful for completely re-writing the user resource.

 

Example:

PUT /scim/v2/Users/80d60b37-3c75-4e41-9bb0-ae6588b6448d
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiwicGVyIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX


{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
   "name": {
       "givenName": "Test",
       "familyName": "User"
   },
   "emails": [{
       "primary": true,
       "value": "employee@company.com",
       "type": "work"
   }],
   "locale": "es",
   "timezone": "Europe/Brussels",
   "title": "Senior Full-Stack Engineer",
   "addresses": [{
       "type": "work",
       "primary": true,
       "value": "21B Baker St., London"
   }]
}

 

• DELETE /Users/{id}

The delete request deactivates the user. Please note, the delete request does not hard-delete the user and that this action is reversible (soft-delete). This is the same as PATCHing with "active": false. A valid DELETE request will be responded with 204 No Content.

Example:

DELETE /scim/v2/Users/80d60b37-3c75-4e41-9bb0-ae6588b6448d
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Authorization: Bearer 
yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiwicGVyIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX

 

Group Endpoints

SCIM Groups are equivalent to monday.com Teams. You can create/delete teams, rename teams, assign and unassign users from teams. Keep in mind, assignment and unassignment are available only by using the PATCH HTTP verb.

For privacy measures, we recommend coordinating the team provisioning with the monday.com admin, in order to avoid users losing access to their data or users gaining access non-intentionally.

 

Group attributes

Groups have both a displayName, which is the Group displayed in the Teams page, and a members attribute (a list of provisioned users assigned to that group).

 

The following table presents all team attributes supported in monday.com’s SCIM API:

monday.com Attribute	SCIM API Attribute(s)	Description	Example Value
Name (required)	displayName	The team's displayed name	"displayName": "R&D Department"
Users	members	List of users assigned to the team	"members": [{                     "value": "80d60b37-3c75-4e41-9bb-ae588b6448d",                     "$ref": "http://monday.lvh.me/scim/v2/Users/80d60b37-3c75-4e41-9bb0-ae688b6448d",                   "display": "Ben Frank",                    "type": "User"            }]

 

• GET /Groups

This returns a paginated list of teams. The default item per page (itemPerPage) is 50. You can use a filter to search for teams; you can only search by their displayName and only the eq operator is supported.

 

 

Below is an example of a paginated list of groups request:

GET /scim/v2/Groups?filter=displayName eq "Developers"
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiwicGVyIjoic2NTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX

 

• GET /Groups/{id}

This retrieves a specific team matching the supplied SCIM ID. To find out a team's SCIM ID, you can send a GET request and filter for their displayName.

 

Example:

GET /scim/v2/Groups/80d60b37-3c75-4e41-9bb0-ae6588b6448d
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowC4wMDBaIiwicGVIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX

 

• POST /Groups

This creates a new team and it must include the displayName attribute.

 

Example:

POST /scim/v2/Groups
Host: company.monday.com
Accept: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiicGVyIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX
{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "displayName": "Chess Players",
   "members": []
}

 

• PATCH /Groups/{id}

This assigns/unassigns/renames a team.

1. Assigning users

To assign users, you'd have to send an 'Add' operation, with the value being the SCIM ID of the user you want to add.

Assign to team example:

PATCH /scim/v2/Groups/80d60b37-3c75-4e41-9bb0-a6588b6448d
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBIiwicGVyIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX
{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "Operations": [{
       "op": "Add",
       "path": "members",
       "value": [{
           "value": "711f99b8-d6d1-41ad-860e-4896b7e8b3d6"
       }]
   }]
}

 

1. Unassigning users

To unassign users, you'd have to send a 'Remove' operation, with the value being the path to the SCIM ID of the user you want to remove from the team.

Unassign from team example:

PATCH /scim/v2/Groups/80d60b37-3c75-4e41-9bb0-ae688b6448d
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiwicGVyIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX
{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "Operations": [{
       "op": "remove",
       "path": "members[value eq '711f99b8-d6d1-41ad-860e-4896b7e8b3d6']"
   }]
}

 

1. Renaming a team

To rename a team, you'd send a 'Replace' operation with the new name as the value and without a path.

Rename team example:

PATCH /scim/v2/Groups/80d60b37-3c75-4e41-9bb0-ae588b6448d
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiwicGVyIjic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX
{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "Operations": [{
       "op": "replace",
       "path": "displayName",
       "value": "The Avengers"
   }]
}

 

• DELETE /Groups/{id}

This hard-deletes a team in monday.com. Please keep in mind that assigned team members are not deleted, only the team is. A successful request is responded with 204 No Content.

Delete a group example:

DELETE /scim/v2/Groups/80d60b37-3c75-4e41-9bb0-ae6588b6448d
Host: <YOUR_DOMAIN>.monday.com
Accept: application/json
Authorization: Bearer yJhbGc4iOiJIUzI1NiJ9.eyJ0aXXXXXXXXUxNTEsInVpZCI6MSwiaWLkIjoiMjAyMC0XXXXXXMjoxNDowMC4wMDBaIiwicGVyIjoic2NpbTphbGwifQ.J8EXXXXXXXltQZA6PAt9i2F4Ux83XXXXXXXX

 

 

Error Handling

Please find the below table that contains error codes and their possible reason. Check out the third column for resolution suggestions:

 

Keep in mind: The identity provider is the source of truth 

If you connect your monday.com account to SCIM, every data change performed in the monday.com platform will be overridden by the data sent via SCIM. As an example, let's say that a user is provisioned to be part of a team, and then you manually unassign them through the monday.com platform. The next time SCIM provisioning runs, it will re-assign them to the team.

 

Frequently asked questions

• How can an admin generate a new SCIM token?

  • To generate a new SCIM token, open up the admin section of your account. From there, press on the "Security" tab, open up the SCIM section, click on the "Generate" button and copy the generated token.

     

    After entering this token into your identity provider, you should be all set!

 

• What happens if I change my personal attributes in my monday.com account? 

The sync with your identity provider is a one-way sync, and any changes made to a user profile in the monday.com profile or teams page will be overwritten the next time your identity provider syncs with your account. 

• What does this mean for me? 
  • To change any attributes of the user profile you will need to update them in your identity provider.
  • In order to add users to teams or remove users from teams created by your identity provider, you will need to make these changes in your identity provider
  • If you create a Team in monday.com that is not a group in your identity provider it will not be affected by the groups in your identity provider

 

• What happens if I add users to a team in my monday.com account? 

If that team is provisioned by your identity provider, these users will eventually be removed from the team and replaced by users that are provisioned to the matching identity provider Group. Otherwise, if the team is not provisioned by your identity provider, when you add users to a team in your monday.com account, they will remain in that team.

 

• Why can't I deactivate or change the user type of an admin who generated the SCIM token?

If an admin on your account has previously generated a SCIM token, it will not be possible to deactivate their user or change their user type from an admin to non-admin. This restriction is in place in order to prevent SCIM provisioning from failing on your account. You can read all about how to get around this in this article! 

 

• What happens to existing users in my account when I activate SCIM provisioning?

Existing users in your monday.com account will be affected in the following way:

• Users whose email exists in both your monday.com account and identity provider will now be managed by the identity provider, and their details will update to match what is configured for them in the identity provider (attributes, teams, role, etc.)
• Users that exist in your account but not in the identity provider will not be affected, but they will also not be controlled by the identity provider until they are added to it
• Users that exist in the identity provider but not in your monday account will be provisioned and added to your monday account 

 

• Can I sync departments via SCIM?

At the moment it is not possible to sync the department attribute of users from the identity provider to your monday.com account.

 

• What happens if a user is part of multiple groups with different monday.com roles in the identity provider? 

If a user is part of multiple groups with different roles, for example, a group that contains viewers and a group that contains members, the stronger monday.com role will be assigned to the user. The role hierarchy is Admin > Member > Viewer > Guest.

 

• What happens if a user is assigned to multiple custom roles? 

When a user is assigned to multiple custom roles, they will be assigned to the last custom role passed by the identity provider, based on the highest base role (Admin > Member > Viewer > Guest).

 

• What emails are sent to newly SCIM provisioned users? 

Newly created users via SCIM provisioning receive a "welcome to monday" email around 1 hour after being created. They don't receive any invitation emails.

 

 

 

If you have any questions, please reach out to our team right here. We’re available 24/7 and happy to help.