SCIM overview

Automatically provision users and teams with TeamRetro SCIM

System for Cross-domain Identity Management (SCIM) is a protocol for user management across multiple applications. It allows your IT or Operations team to provision, deprovision, and update user or team data in TeamRetro using your existing identity provider.

TeamRetro SCIM supports:

• Provisioning/deprovisioning of users
• Provisioning/deprovisioning of user account roles
• Provisioning/deprovisioning of teams
• Provisioning/deprovisioning of user team roles (per team)
• Updating team names

• Updating user names

  
  

How user matching works

When a SCIM user is provisioned, TeamRetro identifies the corresponding TeamRetro user account by comparing the SCIM userName to existing users' email addresses. The comparison is case-insensitive, trims whitespace, and is rejected entirely if the userName value isn't a syntactically valid email address. Email addresses stored on TeamRetro user accounts are normalised the same way, so the user who signed up as BJensen@Example.com (stored as bjensen@example.com) still matches a SCIM userName of BJensen@Example.com.

• If an existing TeamRetro user's email matches the SCIM userName , the SCIM user is linked to that account. Subsequent SCIM updates flow through to that same account.
• If no existing user matches, a new TeamRetro user is created using the SCIM userName as the email address.
• If a SCIM user's userName later changes to match a different existing TeamRetro account, TeamRetro automatically merges the two accounts, preserving retrospective history. This merge is not reversible - please contact TeamRetro support before changing userName  if you're unsure whether a TeamRetro account already exists at the destination address.

Important: TeamRetro does not match on the SCIM emails[]  array, on externalID, or on any other attribute - only on userName . Make sure your identity provider maps userName to the same email address your users authenticate with via SSO. For Entra ID specifically, see the SCIM Provisioning with Entra ID article.

Detailed setup instructions for common identity providers can be found below:

• Set up TeamRetro SCIM with OneLogin
• Set up TeamRetro SCIM with OKTA
• Set up TeamRetro SCIM with Microsoft Azure AD

Our SCIM API documentation can be found at SCIM API Documentation

Prerequisites

You must have SAML single-sign-on enabled for your organization.

Background: TeamRetro User Model

TeamRetro supports two layers of user roles. At the whole-of-account level, a user can be an Account Owner, Account Admin or Account User. Additionally, within each team, the user can be either a Team Admin or a Team Member. Further information on the specific capabilities of each role can be found in our Roles and Permissions Overview .

An example of how this may appear for a small enterprise is below.

Provisioning Account Roles

Account roles can be provisioned by creating SCIM groups for the Account Owners and Account Admins. By default, TeamRetro will look for a group named TeamRetro-Account-Owners and a group named TeamRetro-Account-Admins. If you have a standard group naming scheme you'd like to use, you can adjust the expected group names via the TeamRetro administration panel under SETTINGS —> API & SCIM —> Account Role Groups.

For example, if you configure the following groups in your identity provider:

• TeamRetro-Account-Owners
  • ab@acme.org
• TeamRetro-Account-Admins
  • bc@acme.org
  • cd@acme.org

Following SCIM synchronization, if we start with the account from the previous documentation section, the new state will appear as below:

Notes on behavior:

• All users sent by SCIM to TeamRetro have at minimum the Account Users role.
• SCIM provisioned account roles are:
  • Existing Account Owners will continue to have account owner access.
  • Existing Account Admins will continue to have account admin access.
  • Existing Account Users will continue to have account user access.
• User's roles at the team-level are not affected.

Provisioning Teams and Team Roles

In addition to provisioning account level roles, you can provision the creation of new Teams and assign users Team Roles via SCIM groups. By default, TeamRetro will look for any SCIM groups matching the TeamRetro-{{TeamName}}-Team-Admins or TeamRetro-{{TeamName}}-Team-Members pattern (based on a group name prefix and suffix match), and create a new team (if required) and provision the team roles. If you have a standard group naming scheme you'd like to use, you can adjust the expected group prefix / suffixes via the TeamRetro administration panel under SETTINGS —> API & SCIM —> Team Provisioning / Team Role Groups.

For example, if you configure the following groups in your identity provider:

• TeamRetro-Development-Team-Admins
  • ab@acme.org
• TeamRetro-Development-Team-Members
  • cd@acme.org
• TeamRetro-Sales-Team-Admins
  • bc@acme.org
• TeamRetro-Sales-Team-Members
  • de@acme.org
  • ef@acme.org

Following SCIM synchronization, if we start with the account from the previous documentation section, the new state will appear as below:

How deprovisioning works

When your identity provider sends a SCIM DELETE request for a user (typically because the user was removed from the directory or all assigned SCIM groups), TeamRetro processes it as follows:

1. Account access is removed. The user's membership in your TeamRetro account is updated - they can no longer sign in to your account, view retros, or access any team data. If the user had no other (non-SCIM) roles on your account, the underlying account membership row is removed; otherwise the SCIM-granted roles are cleared and any pre-existing manual roles remain.
2. The account is unlinked from SCIM. The SCIM record is removed and the underlying user is marked as no longer SCIM-managed.
3. The underlying user record is preserved. The user's name is retained in historical retrospectives, comments, action items, and responses. This avoids showing "Deleted User" next to historical contributions.

Deactivation ( active: false )

By default, an incoming active: false has the same effect as DELETE - the user loses access to your account but their authored content remains attributed. Account owners can change this under Account → Settings → SCIM: with ALLOW SCIM USER DEACTIVATION disabled, an active: false event instead leaves the user as a regular (non-SCIM) account member, dropping only the SCIM-granted roles.

Hard-delete (GDPR / right to erasure)

If you need a user's personal data fully removed - for example to satisfy a GDPR erasure request - contact TeamRetro support. Hard-deletes aren't available via SCIM or via the UI today because they de-attribute the user's historical contributions across all retrospectives, which most customers don't want as a default.

Removing a team

If a SCIM group that was mapped to a TeamRetro team is deleted, TeamRetro removes the SCIM-granted member roles. If that leaves the team with no members at all, the team itself is deleted. If any members remain - including members who were added manually outside SCIM - the team is preserved and is no longer treated as SCIM-managed, so account admins can rename or remove it from the TeamRetro UI.

Notes on behaviour:

• If the team name matches an existing team (e.g. Development) - the existing team will be updated.
• If the team name does not match an existing team (e.g. Sales) - a new team will be created (requires sufficient team slots on your subscription).
• SCIM provisioned team roles are
  • Existing Team Admins will continue to have the team admin role.
  • Existing Team Members will continue to have the team member role.
• Removing an SCIM team group will result in the Team being deleted only if all team members were provisioned via SCIM.
• Any users added to a team will also have the Account User role.
• User's roles at the account-level are not affected.

Supported Attributes

TeamRetro's  /Schemas endpoint advertises the standard SCIM 2.0 User attributes we know about. Additional attributes - including the Entra/Okta enterprise extensions listed below - are accepted at the API and stored on the SCIM record, but are not consumed by the product. The table below documents what we currently do with each attribute.

A note on the manager  attribute

Microsoft Entra ID has a known issue where it generates validation errors against compliant SCIM servers when the manager  attribute is mapped. Because TeamRetro doesn't use manager, we recommend not mapping it in Entra to avoid the errors. See SCIM Provisioning with Entra ID for details.