sentry-enterprise-rbac

Sentry Enterprise RBAC

Overview

Configure Sentry's Organization-Team-Project hierarchy, role assignments, SSO/SAML2 federation, SCIM automated provisioning, API token governance, and audit logging. Covers the full enterprise access control lifecycle from initial setup through ongoing compliance monitoring.

Prerequisites

• Sentry Business or Enterprise plan — team-level roles, SSO, SCIM, and audit logs require Business tier or higher

• Organization Owner or Manager role — only these roles can configure auth, teams, and member roles

• Identity Provider access — admin credentials for Okta, Azure AD, or Google Workspace if configuring SSO/SCIM

• Environment variables set:

  export SENTRY_AUTH_TOKEN="sntrys_..."   # Auth token with org:admin, member:admin, team:admin scopes
  export SENTRY_ORG="your-org-slug"       # Organization slug from sentry.io/settings/
  

Instructions

Step 1 — Establish the Organization-Team-Project Hierarchy

Sentry's access model flows top-down: Organization > Teams > Projects. Members inherit permissions from their org-level role, then gain project access through team membership.

Organization-level roles define the ceiling of what a member can do:

Team-level roles (Business/Enterprise only) add granularity within teams:

A member's effective permissions are the union of their org-level role and all team-level roles they hold. A Member with Team Admin on "payments-team" can manage that team but cannot touch org-wide settings.

Create the team structure:

# Create a team
curl -s -X POST \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "backend-eng", "name": "Backend Engineering"}' \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/teams/" | jq '{slug, name, dateCreated}'

# List all teams with member counts
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/teams/" \
  | jq '.[] | {slug, memberCount, hasAccess}'

# Assign a project to a team (grants team members access to that project)
curl -s -X POST \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$SENTRY_ORG/payment-api/teams/backend-eng/"

# Remove a team's access to a project
curl -s -X DELETE \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$SENTRY_ORG/payment-api/teams/backend-eng/"

# List which teams have access to a project
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$SENTRY_ORG/payment-api/teams/" \
  | jq '.[].slug'

Manage team membership:

# List organization members (get MEMBER_ID values)
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/members/" \
  | jq '.[] | {id, email, role, expired}'

# Add a member to a team
curl -s -X POST \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/members/$MEMBER_ID/teams/backend-eng/"

# Remove a member from a team
curl -s -X DELETE \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/members/$MEMBER_ID/teams/backend-eng/"

# Update a member's organization role
curl -s -X PUT \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}' \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/members/$MEMBER_ID/"

Step 2 — Configure SSO/SAML2 and SCIM Provisioning

SSO centralizes authentication; SCIM automates the user lifecycle. Configure SSO first, then layer SCIM on top.

SSO/SAML2 setup — Okta example:

1. In Okta Admin Console, create a new SAML 2.0 application

2. Set the Single Sign-On URL to: https://sentry.io/saml/acs/{org_slug}/

3. Set the Audience URI (SP Entity ID) to: https://sentry.io/saml/metadata/{org_slug}/

4. Configure attribute statements:

   Name	Value
   email	user.email
   firstName	user.firstName
   lastName	user.lastName

5. Download the IdP metadata XML or copy the metadata URL

SSO/SAML2 setup — Azure AD:

1. In Azure Portal > Enterprise Applications, add Sentry from the gallery
2. Configure SAML SSO with Reply URL: https://sentry.io/saml/acs/{org_slug}/
3. Set Identifier (Entity ID): https://sentry.io/saml/metadata/{org_slug}/
4. Map claims: emailaddress, givenname, surname
5. Download the Federation Metadata XML

SSO/SAML2 setup — Google Workspace:

1. In Google Admin > Apps > SAML Apps, add a custom SAML app for Sentry
2. Set ACS URL: https://sentry.io/saml/acs/{org_slug}/
3. Set Entity ID: https://sentry.io/saml/metadata/{org_slug}/
4. Map email, firstName, lastName attributes
5. Download the IdP metadata

Activate in Sentry:

1. Navigate to Organization Settings > Auth
2. Click Configure next to SAML2
3. Enter the IdP metadata URL or upload the metadata XML
4. Click Save then Test SSO Login — verify it redirects and authenticates correctly
5. Enable Require SSO to enforce SSO for all organization members
6. Optionally set a Default Role for SSO-provisioned users (typically Member)

SCIM provisioning automates user creation, deactivation, and group sync:

SCIM Base URL:  https://sentry.io/api/0/organizations/{org_slug}/scim/v2/
Authentication: Bearer token (generated in Sentry's SCIM settings page)

# Provision a new user via SCIM
curl -s -X POST \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "name": {"givenName": "Jane", "familyName": "Doe"},
    "emails": [{"primary": true, "value": "[email protected]", "type": "work"}],
    "active": true
  }' \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/scim/v2/Users"

# List SCIM-provisioned users
curl -s -H "Authorization: Bearer $SCIM_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/scim/v2/Users?count=100" \
  | jq '.Resources[] | {id, userName, active}'

# Deactivate a user via SCIM (sets active to false)
curl -s -X PATCH \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{"op": "replace", "value": {"active": false}}]
  }' \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/scim/v2/Users/$SCIM_USER_ID"

# Sync IdP groups to Sentry teams via SCIM Groups
curl -s -X POST \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "backend-eng",
    "members": []
  }' \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/scim/v2/Groups"

SCIM capabilities once connected:

• Auto-create users when assigned in the IdP
• Auto-deactivate users when removed from the IdP group
• Sync team membership from IdP groups to Sentry teams
• No manual user management — the IdP becomes the single source of truth

Step 3 — API Token Governance and Audit Logging

API token scopes — always apply the principle of least privilege:

Create and manage API tokens:

# Create a new auth token via API
curl -s -X POST \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["project:read", "project:releases", "org:read"],
    "name": "ci-cd-pipeline-prod"
  }' \
  "https://sentry.io/api/0/api-tokens/"

# List all active auth tokens
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/api-tokens/" \
  | jq '.[] | {id, name, scopes, dateCreated}'

# Delete a token by ID
curl -s -X DELETE \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/api-tokens/$TOKEN_ID/"

Token hygiene best practices:

• CI/CD tokens: project:releases + org:read only — the minimum for deploys
• Monitoring tokens: event:read + project:read — read-only for dashboards
• Admin tokens: Use sparingly, rotate quarterly, limit to one or two Owners
• Naming convention: `{pur

Content truncated.