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
| Feature | Description |
|---|---|
| Create users | Users 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 users | Name, email, role, and external ID changes in your IdP sync to Shortcut |
| Deactivate and reactivate users | Unassigning 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 Teams | Groups your IdP pushes become Shortcut Teams, matched by name. Member and name changes sync to the Team. |
Supported User Attributes
| Attribute | Required | Description |
|---|---|---|
userName | Yes | The user’s email address. Shortcut identifies users by email. |
emails | No | The primary work email must be the same address as userName. If omitted when creating a user, Shortcut uses userName. |
displayName | No | The user’s name in Shortcut. If omitted when creating a user, Shortcut uses name, then userName. An update without it keeps the current name. |
active | No | false deactivates the user. New users are active unless this is false. |
externalId | No | Your IdP’s ID for the user, up to 128 characters |
roles or role | No | admin, 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.
| Attribute | Required | Description |
|---|---|---|
displayName | Yes | The Team name, up to 63 characters. Team names are unique within a Workspace. |
externalId | No | Your IdP’s ID for the group, up to 128 characters |
members | No | Users 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):
| Setting | Value |
|---|---|
| SCIM Base URL (Okta) or Tenant URL (Entra) | https://api.app.shortcut.com/integrations/scim/YOUR_WORKSPACE_ID |
| Authorization | Header auth with Bearer token |
| Unique identifier for users | userName |
| Unique identifier for groups | displayName |
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
| Problem | What to check |
|---|---|
| Test Connection fails | The 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 roles | The 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 group | Group names must be 63 characters or fewer. |
| A user can’t sign in after provisioning | Provisioning creates the account. Sign-in still goes through your SAML application, and the user must be assigned to it as well. |