SCIM API - Update User Role, List available Roles

Adding another related SCIM 2.0 gap around organization role management.

Summary

Sentry's SCIM API exposes sentryOrgRole during user provisioning, but there does not appear to be a general SCIM-compatible way to:

• update an existing user's organization-level role, or
• discover/list the organization roles that are valid for the current organization.

The closest existing role update endpoint appears to be the non-SCIM organization member API:

PUT /api/0/organizations/{org_slug_or_id}/members/{member_id}/

However, that endpoint is outside the /scim/v2 surface and uses the normal Sentry API/auth model rather than the SCIM bearer token. This means IdP/IGA systems cannot manage the full role lifecycle through SCIM alone.

Why this matters

For SCIM-driven environments, the IdP or IGA platform should remain the source of truth for both user lifecycle and access level.

Today, an organization role can be set when a user is provisioned with sentryOrgRole, but updating that role later is not exposed as a documented SCIM operation. This creates a gap for common access-management workflows such as:

1. provisioning a user as member,
2. later promoting them to manager or changing them to billing,
3. having the IdP/IGA push that change to Sentry without deleting and recreating the user.

Without a SCIM role update operation, role changes have to be handled manually in Sentry, through a separate non-SCIM API integration, or by deprovisioning/reprovisioning the user. That breaks the expected SCIM model and can create audit, reconciliation, and access continuity issues.

Role discovery is also important. Some IGA tools need to retrieve the available roles before presenting a picker, validating an assignment, or generating access review data. Without a role listing endpoint, each integration has to hardcode Sentry-specific role values and restrictions.

Example integration gap

A SCIM client may reasonably attempt a PATCH like:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "sentryOrgRole",
      "value": "manager"
    }
  ]
}

or, if using the SCIM core roles attribute:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "roles",
      "value": [
        {
          "value": "manager",
          "display": "Manager",
          "primary": true
        }
      ]
    }
  ]
}

But the documented SCIM PATCH /Users/{id} behavior currently only covers updating active to false.

There is also no SCIM endpoint such as:

GET /api/0/organizations/{org_slug_or_id}/scim/v2/Roles

or equivalent discovery response that returns the org roles available for this Sentry organization.

Proposed solution

Implement two additional SCIM role-management capabilities under the existing organization-scoped SCIM prefix:

1. Support role updates on existing SCIM users.

   For example:

   PATCH /api/0/organizations/{org_slug_or_id}/scim/v2/Users/{member_id}

   should support replacing the user's organization role using either:

   • Sentry's existing sentryOrgRole attribute, or
   • the SCIM core roles attribute mapped to Sentry's organization-level role.

   The same validation rules used when provisioning a user with sentryOrgRole should apply here.

2. Add a read-only role discovery endpoint.

   For example:

   GET /api/0/organizations/{org_slug_or_id}/scim/v2/Roles

   returning the role values valid for the current organization/plan, with enough metadata for clients to determine whether each role is assignable through SCIM.

   Example shape:

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
     "totalResults": 4,
     "Resources": [
       {
         "id": "member",
         "value": "member",
         "display": "Member",
         "supported": true,
         "scimAssignable": true
       },
       {
         "id": "manager",
         "value": "manager",
         "display": "Manager",
         "supported": true,
         "scimAssignable": true
       },
       {
         "id": "billing",
         "value": "billing",
         "display": "Billing",
         "supported": true,
         "scimAssignable": true
       },
       {
         "id": "owner",
         "value": "owner",
         "display": "Owner",
         "supported": true,
         "scimAssignable": false
       }
     ],
     "startIndex": 1,
     "itemsPerPage": 4
   }
   

   If /Roles is not desirable until the SCIM Roles and Entitlements extension is finalized, a Sentry-specific extension advertised through ServiceProviderConfig would still solve the immediate interoperability problem.

Acceptance criteria

• PATCH /scim/v2/Users/{member_id} can update an existing member's organization role through the SCIM API.
• The role update works with the SCIM bearer token and follows the same permission/validation rules as SCIM user provisioning.
• SCIM User responses continue to include the resulting sentryOrgRole.
• A read-only role discovery endpoint, or equivalent advertised SCIM extension, returns the organization roles available for the current tenant.
• The discovery response indicates which roles are assignable through SCIM and which are unsupported or restricted.
• Invalid or disallowed role values return a SCIM-compliant 400 response with a useful error message.
• Existing Okta and Entra ID provisioning flows continue to work without changes.
• Documentation is updated to describe SCIM role update and role discovery support.

References

• Related issue: getsentry/sentry#115030
• Existing SCIM create-user behavior: sentryOrgRole on POST /scim/v2/Users
• Existing SCIM update-user behavior: PATCH /scim/v2/Users/{member_id} currently only documents active = false
• Existing non-SCIM role update API: PUT /api/0/organizations/{org_slug_or_id}/members/{member_id}/
• SCIM Roles and Entitlements draft may be useful as a future-compatible shape for /Roles

Start by tracing the existing SCIM POST /scim/v2/Users provisioning behavior and PATCH /scim/v2/Users/{member_id} handling, especially sentryOrgRole and bearer-token validation. Compare these with PUT /api/0/organizations/{org_slug_or_id}/members/{member_id}/ and the related issue #115030. Done means role updates and role discovery work through SCIM, invalid roles return useful SCIM errors, existing provisioning flows remain compatible, and the documentation is updated.