SCIM

Overview

SCIM lets your Identity Provider (IdP) create, update, and deactivate Shortcut users, and keep Shortcut Teams in sync with your IdP groups. Shortcut supports SCIM with Okta and Microsoft Entra ID.

Requirements

  • Enterprise or Business plan - SCIM relies on SSO/SAML, which is included on Enterprise plans and available as an add-on on Business plans
  • Owner or Admin access in Shortcut
  • SAML SSO configured on your Shortcut Organization. SSO can remain optional. See SAML.
  • Invitation-only workspace - Set under Settings > Invite New User > Settings
  • SCIM credentials - Contact support@shortcut.com. Support gives you your workspace’s SCIM URL (or, for the Okta catalog app, its Workspace ID) and an API token.

SCIM operates at the Workspace level while SAML operates at the Organization level. Organizations with multiple Workspaces should create separate SCIM applications for each Workspace.

Supported SCIM Features

FeatureDescription
Create usersUsers assigned to the Shortcut app in your IdP are created in Shortcut. A user who already belongs to your Organization is added to the Workspace. A name or email your IdP sends updates the existing user, and attributes it omits keep their current values.
Update usersName, email, role, and external ID changes in your IdP sync to Shortcut
Deactivate and reactivate usersUnassigning or disabling a user in your IdP deactivates them in Shortcut. Shortcut never deletes users through SCIM. Assigning the user again reactivates them.
Push groups as TeamsGroups your IdP pushes become Shortcut Teams, matched by name. Member and name changes sync to the Team.

Supported User Attributes

AttributeRequiredDescription
userNameYesThe user’s email address. Shortcut identifies users by email.
emailsNoThe primary work email must be the same address as userName. If omitted when creating a user, Shortcut uses userName.
displayNameNoThe user’s name in Shortcut. If omitted when creating a user, Shortcut uses name, then userName. An update without it keeps the current name.
activeNofalse deactivates the user. New users are active unless this is false.
externalIdNoYour IdP’s ID for the user, up to 128 characters
roles or roleNoadmin, member, or observer. roles is the standard SCIM attribute and uses the entry marked primary. Okta’s role attribute also works. New users without a role are members, and an update without a role keeps the current one. SCIM shows a workspace Owner as admin. Sending admin keeps the Owner role, but sending member or observer changes it.

Shortcut ignores other attributes, such as title, addresses, and phone numbers.

Supported Group Attributes

Shortcut stores each pushed group as a Team.

AttributeRequiredDescription
displayNameYesThe Team name, up to 63 characters. Team names are unique within a Workspace.
externalIdNoYour IdP’s ID for the group, up to 128 characters
membersNoUsers in the Team. They must already be provisioned to the Workspace.

A Team created through SCIM uses your Workspace’s default workflow. You can change its workflows in the Team’s settings. If your IdP sends a SCIM group delete, Shortcut archives the Team. Pushing the group again unarchives the Team.

SCIM Configuration

Configure these settings in your IdP (field names vary by IdP):

SettingValue
SCIM Base URL (Okta) or Tenant URL (Entra)https://api.app.shortcut.com/integrations/scim/YOUR_WORKSPACE_ID
AuthorizationHeader auth with Bearer token
Unique identifier for usersuserName
Unique identifier for groupsdisplayName

Contact support@shortcut.com to obtain your SCIM URL or Workspace ID and Bearer token.

Configuring Okta with SCIM

Follow Set up SCIM with Okta to add the Shortcut SCIM app from the Okta catalog, connect it to your Workspace, and push groups as Teams.

Configuring Entra ID with SCIM

Follow Set up SCIM with Microsoft Entra ID to connect a Workspace, configure user and group mappings, and manage provisioning and access changes.

Troubleshooting

ProblemWhat to check
Test Connection failsThe URL must be the full SCIM URL from support, including the Workspace ID. The token must be the current one; ask support to issue a new token if you’re unsure.
”Inconsistent userName and primary email”userName and the work email must be the same address. Map both from the same expression.
”Email already in use” (uniqueness)Another Shortcut account already uses that email, possibly one outside your Organization. Contact support.
invalidValue on rolesThe role must be exactly one of admin, member, or observer, with one entry marked primary.
”Group name already in use” (uniqueness)A Team with the same name exists and your IdP tried to create it again. Link the group to the existing Team, or rename one of them.
invalidValue on a groupGroup names must be 63 characters or fewer.
A user can’t sign in after provisioningProvisioning creates the account. Sign-in still goes through your SAML application, and the user must be assigned to it as well.