SCIM

System for cross-domain identity management (SCIM) enables you to automate user management and provisioning and management between Miro and your identity provider (IdP).

Available for: Enterprise plan
Set up by: Company Admins

New synchronization model 

Miro is introducing a new SCIM synchronization model where a SCIM group now corresponds to a Miro user group, replacing the previous model where a SCIM group mapped to a Miro team. We recommend migrating to user group-based SCIM synchronization as soon as possible.

Unlike teams, user groups aren't confined to a single team, so you can sync organizational structures that span multiple teams instead of being limited to a 1:1 team mapping. User groups also plug directly into the same permissions model used across Miro. You can share boards and Spaces with a group, @mention a group in comments to notify all its members, and manage groups programmatically via the User Groups API, so provisioning through your IdP now stays in sync with how sharing and access already work in Miro.

Note: This is the most recent version of the API where a SCIM Group corresponds to a Miro user group. Adding or removing members of a SCIM Group changes the membership of the Miro user group.

Important to know

• SAML based SSO must be properly set up and be functional in your Enterprise plan before you start configuring automated provisioning. See the guide to configuring SAML SSO.
• Syncing IdP groups with Miro user groups is optional. You can optionally link and sync your IdP groups with user groups in Miro. A SCIM Group corresponds directly to a Miro user group — creating, updating, or deleting a SCIM Group creates, updates, or deletes the corresponding user group, and adding or removing members changes that user group's membership. You can also create and manage user groups directly using the User Groups API. Unlike teams, a user group isn't confined to a single team, so you can sync organizational structures that span multiple teams. For more information about how the SCIM API enables you to manage groups, see the Miro Developer documentation.

• Email address changes in SCIM include the following validation rules:

  • Managed User Check: If the user's current domain is not claimed by the organization initiating the SCIM request, the email update is blocked and throws a 400 error.
  • Target Email Domain Verification: If the target email domain is claimed by an organization other than the one initiating the SCIM request, the email update is blocked and throws a 400 error. If the target email domain is claimed by the organization initiating the SCIM request, the email update is allowed without requiring email confirmation. Audit logs record the update in each organization where the user is a member.
  • Domain Control and SSO: Email updates are allowed based on domain verification through Domain Control (IDC) or Single Sign-On (SSO). If the target email domain is verified through CD or SSO by the initiating organization, the update can proceed.

  A diagram of the SCIM email change validation workflow

Rules under which Miro SCIM operates

• The SCIM-synced changes are primarily applied to newly assigned users. Membership changes are applied directly and immediately: an add, remove, or replace operation on a SCIM Group's members adds or removes that member from the corresponding Miro user group, with no separate "push" step required. For instance: a) if a user is a member of User Group A on the Miro side and your IdP sends an update to add them to User Group B, their membership in User Group A is unaffected — they simply also become a member of User Group B. b) if your IdP sends an update containing changes to User1, other user group members are unaffected.
• All users provisioned under SCIM are assigned the default license of your subscription: a) For Enterprise subscriptions without Flexible Licensing Program: a Full license. If your subscription runs out of licenses the users start getting provisioned under Free Restricted license. b) For Enterprise subscriptions with Flexible Licensing Program activated: Free or Free Restricted license depending on the default subscription license. 
  If you need some of the users to be provisioned under a license different to the default one: as stated above, all users are provisioned with the default license. However, you can immediately update all or some of them using the UserType attribute with a Full value. Users updated with the attribute will be upgraded to the Full license with no downtime on the user-end. Note: adding a member to a user group via SCIM also reactivates or recreates that member if they were previously deactivated or deleted, and upgrades their license to Full.
• All users provisioned under SCIM are also affected by the Domain control feature. This means that if a user is a member of only one security group in your Identity provider but your Domain control settings define 3 teams as the designated ones the user will also be added to those 3 teams.

• To protect the service Miro limits the number of API calls available every 30 seconds:

  Request type	Limit level
  GET scim/users GET scim/users/{userId}	First Rate Limit Level 1
  POST scim/users/{userId} PUT scim/users/{userId} PATCH scim/users/{userId} DELETE scim/users/{userId}	Third Rate Limit Level 3
  GET scim/Groups PATCH scim/Groups/{groupId}	Fourth Rate Limit Level 4
  GET scim/Groups/{groupId}	Third Rate Limit Level 4

  For details on limit levels please see here. If the number of requests exceeds the limit, Miro will return the standard 429 Too many requests.

Supported features

Detailed Miro SCIM schema can be found here. Detailed information on the Groups (user groups) endpoints can be found in the Groups API documentation.

Miro supports the following provisioning features:

• Create new users 
  New users assigned to Miro application in IdP will be created in your Miro Enterprise subscription as Enterprise Members. Users that are added to an IdP group synced to a Miro user group will be added to that user group directly as members.
   
• Push user profile updates 
  For the supported attributes and changes see below.
   
• Sync IdP groups to user groups 
  Sync your IdP groups to user groups within your Miro Enterprise subscription to automatically manage membership. Because a SCIM Group corresponds directly to a Miro user group, add and remove operations from your IdP apply immediately to the user group's membership — there's no separate push/overwrite step needed.
   
• Remove users from IdP group/Miro user group (not the Enterprise subscription, see below) Removing a user from an IdP group removes them from the corresponding Miro user group immediately. This removes the user from the user group only. It does not remove them from any team or from the organization, does not transfer board ownership, and does not change their license. There's no last-admin restriction for user groups, and removing a user who isn't already a member is a no-op.
   
• Deactivate users 
  Deactivating/deleting a user or disabling a user's access to the application in the IdP will deactivate the user in your Miro Enterprise plan. The user moves from an Active to a Deactivated state (and users section, respectively) and stops consuming a license. Deactivation alone does not change the user's user group memberships or reassign board ownership. 
  
  Removing a user from the Enterprise subscription is not supported by default. Still, you can manually add the functionality using API to have the user completely removed from the subscription instead of setting them to the Deactivated status. In this scenario, the content is reassigned to respective Team members. It's impossible to set which Admins will get the ownership over automatically reassigned content, but this can be set when you manually deactivate a user in Miro settings. Removing a user from a user group (see above) never triggers content reassignment on its own.
   
• Reactivate users 
  Assigning a user back to the application or reactivating the user profile in the IdP will reactivate them in your Miro Enterprise subscription if they were previously provisioned and deactivated.
   
• Automating billing group allocation 
  Auto-assign new users to billing groups using SCIM. Once your Identity Provider (IdP) is set up, link your cost centers to your billing groups. This ensures every current and future user from these cost centers gets automatically sorted into the right billing category.
   
• Share boards and Spaces with a group Because a Miro user group plugs into the same permissions model used across Miro, you can share boards and Spaces directly with a user group synced from your IdP, instead of adding members individually.
   
• @mention a group in comments @mention a user group in board comments to notify all of its members at once.
   
• Manage groups programmatically Create, update, and delete user groups directly using the User Groups API, independent of your IdP sync.

You can also remove users from your Enterprise plan by sending a direct Delete API call - please see the documentation here. Note that only direct calls will remove the users. Delete events initiated by your identity solution will be treated as a request to Deactivate.

Supported attributes

Note: Email (the primary parameter / unique identifier / username) is the only value required by Miro and must be in the form of an email. The email update is only possible for already synced users — the first sync must happen when their email in the IdP and Miro is the same, otherwise Miro won't recognize the user and a duplicate Miro profile under the new email will be created. The email update must happen in the user's IdP profile, not in the assignments list. Unlike with other attributes, updating the user's Email will send them a notification: both the old and the new email address will receive a letter letting the user know that they are now to use their new email address to log into Miro.

⚠️ Password changes are not supported and there are no immediate plans to start supporting this change. ⚠️ Username, UserType and roles.value cannot be updated for Deactivated users.

All attributes will be displayed in the exported CSV user list that can be downloaded from the Active Users section.

Configuring SCIM

Step 1: Enable SCIM option in Miro

To enable SCIM for your Miro Enterprise plan, go to the Company settings > Enterprise integrations, enable the SCIM Provisioning feature. There you can get the Base URL and the API Token for configuring your IdP.

Step 2: Configure your Identity Provider

The setup will depend on the Identity Provider you use. Miro supports preconfigured Okta and Entra ID however you can use any Identity Provider of your choice for as long as it allows setting up SCIM.

OKTA - see the setup instruction here.

Entra ID - see the setup instruction here.

Generate new token

1. Go to the Company settings > Enterprise integrations.
2. In the SCIM Provisioning section, click Generate new token.
3. In the Generate new SCIM token window, click Generate.
4. After generating a new token, you must configure the new token in your IdP provider.

Possible issues and how to resolve them

1. Users do not get provisioned due to an allowlist error.
Please make sure that the user's domain address is added to your allowlist in the Security settings.

2. If you authenticate your end-users with one identity solution (IDP1) but would like to enable SCIM via a different one (IDP2), this is possible on two conditions:

1. the IDP2 can do API calls with the bearer token.
2. both identity providers are in sync (so SCIM-provisioned users exist in IDP1 as well and therefore are able to authenticate with Miro).

For more information on SCIM errors, see our documentation here. If the issue persists, you can reach out to the Miro Support Team.