Set up SCIM2 for Label Studio

System for Cross-domain Identity Management (SCIM) is a popular protocol to manage access for services and applications across an organization.

Using a SCIM provider, you can manage access to Label Studio Enterprise workspaces, and grant roles to individual users and groups.

Requirements

Label Studio Enterprise uses the SCIM Version 2.0 standard.

Label Studio Enterprise follows SCIM RFC 5741 and can be integrated with any access management services that support the standard.

For more information on SCIM workflows, see How SCIM works with Label Studio Enterprise.

Prerequisites

• SCIM interacts with your SSO integration. Before you begin, you must have SSO already configured. If you do not have SSO set up yet, then follow Set up SSO.

• You will need a Label Studio API token from the organization owner. Both Legacy tokens and JWT-based Personal Access Tokens (PATs) are supported.

Set up SCIM (general steps)

The following steps apply to any SCIM 2.0-compatible identity provider. For IdP-specific walkthroughs, see IdP-specific setup guides.

Step 1: Add Label Studio as an application in your IdP

If you have not already created an application for Label Studio as part of your SSO setup, create one now in your IdP. SCIM provisioning is typically configured on the same application used for SSO (SAML 2.0).

Step 2: Enable SCIM provisioning

In your IdP’s application settings, enable SCIM (or “automatic”) provisioning and configure the connection:

After entering these values, use your IdP’s Test Connection feature (if available) to verify that Label Studio is reachable and the token is valid.

Step 3: Configure user attribute mappings

Map your IdP’s user attributes to SCIM target attributes. The following attributes are supported by Label Studio:

Step 4: Enable provisioning actions

Enable the following provisioning actions in your IdP (the exact labels vary by provider):

• Create users
• Update user attributes
• Deactivate users

Step 5: Configure group provisioning

If you plan to use groups to manage roles, workspace membership, and project access, enable group provisioning in your IdP. The required group attributes are:

Step 6: Configure group mappings in Label Studio

In Label Studio, go to Organization > Security > SSO & SCIM to map your IdP groups to roles, workspaces, and projects:

• Organization Roles to Groups Mapping – Map groups to organization-level roles (Administrator, Manager, Reviewer, or Annotator). The most elevated role wins if a user belongs to multiple groups. For more information on roles, see Roles in Label Studio Enterprise.
• Workspaces to Groups Mapping – Add groups as members to workspaces. Users with Manager, Reviewer, or Annotator roles can only access workspaces they have been added to.
• Projects to Groups Mapping – Map groups to project-level roles (Annotator, Reviewer, or Inherit). A group can have different roles across different projects.

You can also configure these mappings via the API. For details, see Group mapping reference.

Step 7: Assign users and groups to the application

In your IdP, assign the users and/or groups that should be provisioned to the Label Studio application. Only assigned users and groups are synced.

Step 8: Start provisioning

Trigger an initial sync from your IdP. Depending on the provider, the first sync cycle may take longer than subsequent incremental syncs. Monitor your IdP’s provisioning logs for errors.

After provisioning completes, verify in Label Studio that users appear with the expected roles and group memberships.

IdP-specific setup guides

Okta

To set up SCIM provisioning specifically with Okta:

Entra ID

To set up SCIM provisioning specifically with Microsoft Entra ID (formerly Azure AD):

curl -X POST "https://<your-label-studio-host>/api/scim/settings" \
  -H "Authorization: Token <owner-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "roles_groups": [
      ["Administrator", "LS-Admins"],
      ["Manager", "LS-Managers"],
      ["Reviewer", "LS-Reviewers"],
      ["Annotator", "LS-Annotators"]
    ],
    "workspaces_groups": [
      ["Engineering", "LS-Engineering-Team"],
      ["QA", "LS-QA-Team"]
    ],
    "projects_groups": [
      {"project_id": 42, "group": "LS-Project42-Annotators", "role": "Annotator"},
      {"project_id": 42, "group": "LS-Project42-Reviewers", "role": "Reviewer"},
      {"project_id": 99, "group": "LS-AllProjects", "role": "Inherit"}
    ]
  }'

Group mapping reference

Both SAML and SCIM use the same group mapping format and the same underlying mapping logic. The mapping types are configured independently for each protocol (SAML settings and SCIM settings are separate), but the behavior is identical.

Organization role mapping (roles_groups)

Maps a group from your IdP to an organization-level role.

Format: ["<RoleName>", "<GroupName>"]

Available roles:

Behavior when a user is in multiple role groups: The most elevated role wins. For example, if a user is in both an Annotator group and a Manager group, they get the Manager role.

Behavior when a user is removed from all role groups: Their role is set to Deactivated (subject to the manual_role_management flag).

Workspace mapping (workspaces_groups)

Maps a group from your IdP to a Label Studio workspace.

Format: ["<WorkspaceTitle>", "<GroupName>"]

• Workspaces are automatically created when a SCIM group push or SAML login triggers the mapping. However, the /api/scim/settings endpoint validates that referenced workspaces already exist—create them first, or use the UI to save settings.
• A user can be mapped to multiple workspaces through multiple group memberships.
• SCIM: removal respects the manual_workspace_management billing flag—if enabled, users are not automatically removed from workspaces when they leave a group.
• SAML: workspace sync behavior is controlled by the MANUAL_WORKSPACE_MANAGEMENT environment variable (default: True). When False, all SAML-mapped workspaces are reset and re-applied on each login.

Project role mapping (projects_groups)

Maps a group from your IdP to membership in a specific project, with a project-level role.

Format: {"project_id": <id>, "group": "<GroupName>", "role": "<Role>"}

Available project roles:

• project_id must be an existing project in your organization.
• The most elevated role wins when a user is in multiple groups mapped to the same project.
• Removal respects the manual_project_member_management billing flag.
• When SCIM project group assignments exist for a user, SAML project sync is skipped for that user to avoid conflicts.

SCIM user lifecycle

SAML and SCIM interaction

If your organization uses both SAML SSO and SCIM provisioning, be aware of the following interactions:

• Group mappings are configured separately. SAML settings (/api/saml/settings) and SCIM settings (/api/scim/settings) each have their own roles_groups, workspaces_groups, and projects_groups. You can configure identical mappings in both, or use different mappings for each protocol.
• SCIM project mappings take precedence over SAML. When SCIM-driven project group assignments exist for a user, SAML skips its project role sync for that user entirely, to avoid conflicts.
• Deleting SAML settings clears SCIM group assignments. Using DELETE /api/saml/settings wipes all group assignment records and resets SCIM group settings for the organization. If you need to reconfigure SAML, re-save your SCIM settings afterward and wait for the next group sync to rebuild assignments.
• manual_role_management is shared. The per-org override in SAML settings takes precedence over the billing/environment default for both SAML and SCIM role removal behavior.
• SSO login can still change roles even with SCIM. If a user authenticates via SAML and SAML role mappings are configured, the role may be re-evaluated on login based on SAML group attributes—potentially overriding a role set by SCIM. To avoid this, either use the same mappings in both, or configure role mappings in only one of the two.

For more information on SAML SSO setup, see Set up SSO authentication for Label Studio.

Troubleshooting SCIM

Provisioning test connection fails

• Verify the SCIM endpoint URL ends with /scim/v2 (or /scim/).
• Verify the bearer token belongs to the organization owner (SCIM API requires owner-level authentication). Both legacy API tokens and PATs are accepted.
• Check that the Label Studio instance is reachable from the internet (or via your network configuration).

User created but has wrong role

1. Verify the user is assigned to the correct group in your IdP.
2. Verify the group is assigned to the Enterprise Application (in Entra ID) or pushed to the application (in Okta).
3. Verify the group displayName in your IdP exactly matches (case-sensitive) the name in Label Studio SCIM settings.
4. Ensure a provisioning cycle has completed after the group assignment (or trigger on-demand provisioning).

Users not appearing in workspaces or projects

• Group provisioning must be enabled in the attribute mappings.
• The group must be assigned to the Enterprise Application (just existing in Entra ID is not enough).
• SCIM group settings in Label Studio must be configured before or at the same time as the groups are pushed. If settings are configured after groups were already synced, save the SCIM settings again to trigger re-evaluation.

Unsupported attribute errors in provisioning logs

Remove any default IdP attribute mappings that target attributes not in the Label Studio SCIM schema. See the Mappings to remove section above for common attributes to remove.

Email case mismatches

Label Studio normalizes all emails to lowercase for both SAML and SCIM operations. Alice@Contoso.com and alice@contoso.com are treated as the same user. No special configuration is needed.

Group name mismatches

Group name matching in SCIM settings is case-sensitive. LS-Admins and ls-admins are treated as different groups. Ensure exact casing matches between your IdP group names and Label Studio mapping configurations.