What can we help you with?

SCIM Provisioning API

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. 

Note: SCIM Provisioning is available on the Enterprise plan only.

 

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, Azure AD, 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 Azure AD
    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.

Note: Make sure to replace <YOUR-DOMAIN> above with your account URL name (if your account URL is myaccount.monday.com, you would write "myaccount" here).

 

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.

CPT2105231258-1337x735.gif

 

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
Note: In requests that contain data, e.g. PATCH, PUT and UPDATE you should add the Content-Type header with value application/json

 

SCIM Endpoints

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

 

The default value is "member"

"userType": "admin"

 

Note: All endpoints require a user to be Provisioned! If your request is responded with 404 Not Found, please make sure to post that user beforehand in order to provision them.

 

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
Note: The startIndex is 1-based, meaning the first user is user number 1, not number 0.

 

 

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

 

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

If a user with that email already exists in monday.com, the following will occur:
  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.

Note: Active and userType attributes cannot be changed in a PUT request, but rather by using PATCH only.

 

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.

Note:  If you assign a group to monday.com app within your identity provider and there is already a monday.com team with the same name, then the identity provider’s group will replace it.

 

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

image_11.png

 

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.

 

Note: The startIndex is 1-based, meaning the first team is user number 1, not number 0.

 

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",
      "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:

image_2__14_.png

 

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.

      CPT2105231258-1337x735.gif

      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! 

 

 

If you have any questions, please reach out to our team by using our contact form. We're available 24/7 and happy to help! 



Have more questions? Submit a request