This guide walks you through setting up role-based permissions for your Enterprise organization. This lets you control which features specific teams or groups of members can access, rather than giving everyone the same permissions.
Before you start, make sure you're familiar with:
Manage groups and group spend limits on Enterprise plans — how to create and manage groups
Manage custom roles on Enterprise plans — how custom roles and capabilities work
Before you begin
You'll need Owner or Primary Owner access to your Enterprise organization.
Log out and log back in to your Claude account before you start. This ensures the updated admin settings sidebar appears, with the new Groups and Custom roles pages under People.
Back up your member list. Export a CSV of your current members from Organization settings > Members before making any changes. If something goes wrong during migration, this gives you a reference to restore access. See Manage members on Team and Enterprise plans.
Dual-seat plans: If your organization is on a dual-seat Enterprise plan (with Chat and Chat + Claude Code seats), custom roles don't override seat-level restrictions. A member assigned to a Chat-only seat can't access Claude Code even if their custom role grants it. Plan your role structure with seat assignments in mind.
If you plan to use identity provider (IdP) groups from Okta, Entra ID, or another provider, make sure SCIM directory sync is configured. See Set up JIT or SCIM provisioning.
Provisioning mode note: If your organization uses Invite only or JIT provisioning, you can only use manually created groups for RBAC. SCIM-synced groups aren't supported in these modes.
Planning your role structure
Before creating anything, decide which features each team or group of members should have access to. Here are three common patterns:
Base plus additive roles
This is the recommended approach for most organizations. Create a "Standard Access" role for everyone with common features like web search, memory, and projects. Then create additive roles that grant specific capabilities — for example, a "Cowork Enabled" role that only adds Cowork. Assign all members to the base role through an "All Users" group, and add specific members to additional groups that layer on extra features.
This pattern is flexible because permissions are additive — combining a base role with additive roles composes cleanly without conflicts.
Tier-based roles
Create distinct tiers: "Full Access" with all features, "Standard Access" with most features, and "Restricted Access" with minimal features. Each member goes into exactly one group assigned to one tier.
Department-based roles
Create roles that map to departments: "Engineering" with Cowork, Claude Code, and code execution; "Research" with web search, memory, and projects; "Business" with web search and projects only. Assign each department group to its corresponding role.
Step 1: Audit your current settings
Review which features are currently enabled or disabled at the organization level in Organization settings > Capabilities.
Go to Organization settings > Organization to export or review your member list.
Note each member's current built-in role (User, Admin, or Owner).
For each team or department, decide which features they need access to.
Remember: any feature you want to control per-group must be enabled at the organization level. If a feature is toggled off at the organization level, no custom role can grant access to it.
Important: Unlike members with the User role, members assigned to Custom roles don't automatically inherit organization-enabled capabilities. Every capability a Custom roles member needs must be explicitly granted by a custom role assigned to one of their groups.
Step 2: Create custom roles
Create your custom roles before enabling any features or migrating members. This ensures your roles are ready to enforce access the moment features turn on.
Navigate to Organization settings > Custom roles.
Click “+ Add role.”
Name the role and toggle the appropriate capabilities.
Click “Add role.”
Repeat for each role in your plan.
See Manage custom roles on Enterprise plans for details on available capabilities.
Step 3: Create groups and assign roles
Navigate to Organization settings > Groups.
Click “Add group” to create a group for each team or tier in your plan.
Add members to the appropriate groups.
Assign each group to the custom roles you created in step 2.
If you use SCIM directory sync, you can sync groups from your identity provider instead of creating them manually. For details on SCIM group sync, see Manage groups and group spend limits on Enterprise plans.
Multiple organizations under the same parent organization: Groups are managed at the parent organization level and propagate to all child organizations. You may see members from other organizations listed in a group — this doesn't mean they have access to your organization. Custom roles assigned to a group only grant capabilities to members who are part of your specific organization.
Step 4: Verify group and role assignments
Before migrating members to Custom roles, confirm that every member you plan to migrate is in at least one group assigned to a custom role. Members who are migrated without group or role coverage will lose access to all governed features.
Navigate to Organization settings > Members.
Use the Role and Group filters to identify members who aren't assigned to any group.
Alternatively, click "Export CSV" to download the full member list with role and group columns for review.
Add any unassigned members to the appropriate groups before continuing.
Step 5: Migrate members to Custom roles
For custom role capabilities to take effect, members must have their role set to “Custom roles.” Members with the User, Admin, or Owner roles get their permissions from those roles directly, not from custom roles.
Important: Complete this step only after you've created your custom roles, created your groups, and verified all members are assigned to groups (steps 2–4). Members moved to Custom roles before setup is complete will immediately lose access to all governed features.
Choose the migration path based on whether your organization already enabled group mappings:
Path A: Enable group mappings (only if already in use)
Use this path only if your organization already enabled group mappings for role assignment. If you aren't already using this setting, skip to Path B.
Navigate to Organization settings > Identity and access.
In the role mappings section, assign the IdP groups you want governed by custom roles to the Custom roles role.
Save your changes. Members in those IdP groups are migrated to Custom roles on the next sync.
Members in IdP groups mapped to Custom roles follow the permissions of the custom roles assigned to their groups in Claude. Members in IdP groups mapped to User follow the organization-level capability settings. If a member is in groups across both mappings, Custom roles takes precedence.
Path B: Bulk assignment tool
Use this path if your organization hasn’t enabled group mappings.
Warning: If you didn’t already enable group mappings, do not enable it during RBAC setup. Enabling it without first assigning all members to mapped groups can result in members losing access to your organization.
Navigate to Organization settings > Members.
Use the Role and Group filters to select the members you want to migrate.
Use the bulk assignment tool in the Members table to change the selected members' role to Custom roles.
We recommend migrating a pilot group first — one team or department — and verifying their access is correct before expanding to the rest of the organization.
Gradual rollout
Whichever path you use, we recommend migrating in stages:
Start with a pilot group of one team or department.
After migration, verify the pilot group has the correct feature access based on their group and role assignments.
If something isn't right, switch the affected members back to their previous role while you adjust.
Expand to more members once you've confirmed the setup works.
Step 6: Enable features at the organization level
Only enable organization-level features after roles, groups, and member migration are complete. This ensures custom role capabilities are already in place, with no window where unauthorized members could access a feature.
For any feature you want to control per-group:
Navigate to the feature's settings page in Organization settings (for example, Organization settings > Cowork).
Enable the feature at the organization level.
Enabling a feature at the organization level doesn't mean everyone gets it—custom role permissions are already in place to control who can use it. Think of the organization-level toggle as making the feature "available for role-based assignment" rather than "on for everyone."
Step 7: Verify and monitor
Spot-check access: Check a few members from each group to confirm they see the right features.
Test the restricted state: Log in as (or ask) a member who should not have a feature like Cowork. They should see it greyed out with the message "Contact your admin to request access to this feature."
Test the granted state: Confirm a member who should have the feature sees it working normally.
Check edge cases: Test members in multiple groups, members with no group, and new members joining via SSO.
Permission changes take up to five minutes to fully sync across the platform. Members may need to refresh their browser to see updated access.
Using SCIM with role-based capabilities
SCIM connects to your role-based capabilities through two mechanisms that work together.
IdP group-to-role mapping
This controls which built-in role a member gets when they're provisioned. Map your IdP groups to “Custom roles” so that new members' access is automatically governed by custom role capabilities.
Navigate to Organization settings > Identity and access.
In the role mappings table, map your IdP groups to “Custom roles.”
Group sync
This pulls your IdP groups into Claude so they can be assigned to custom roles.
Navigate to Organization settings > Groups
Click “Check for updates” in the SCIM sync section.
When prompted to sync Groups, Members, or Both, select Groups only. Syncing Members can affect provisioning and member access.
Your IdP groups appear as SCIM-sourced groups in the list.
Assign SCIM groups to custom roles just like manually created groups.
In your IdP, only push the groups you actually intend to use for RBAC or spend limits. Syncing all IdP groups can slow page loads in the Groups section.
Note: Custom role permissions only apply to members with “Custom roles” selected in Organization settings > Organization. If you map an IdP group to a different role (like User) through the group-to-role mapping but assign that same SCIM group to a custom role, the custom role's permissions have no effect—the member gets their permissions from their assigned role instead. To use custom roles, make sure the IdP group is mapped to “Custom roles.”
Ongoing management with SCIM
To grant a member access to a feature, add them to the appropriate IdP group. On the next sync, they pick up the custom role assigned to that group.
To revoke access, remove them from the IdP group. On the next sync, the permission is removed.
Click “SCIM sync” in the Groups section to force an immediate sync rather than waiting for the next scheduled sync.
Rollback plan
If you notice your role structure is misconfigured after migration:
Turn off any organization-level features that were enabled as part of the migration.
Change affected members back to their previous built-in role (for example, User).
They immediately regain the static permissions from that role, and custom role permissions stop applying.
Adjust roles and groups as needed, then re-migrate.
If you enabled group mappings during setup and lost admin access, follow the recovery steps in Set up JIT or SCIM provisioning under "I lost Admin/Owner access after enabling group mappings."
Frequently asked questions
Do I need to enable a feature at the organization level if I only want some members to have it?
Yes. The organization-level toggle must be on for custom roles to control per-member access. If a feature is off at the organization level, no one can access it regardless of their role. Think of it as a main switch—custom roles control who gets access underneath it.
What happens if a member set to “Custom roles” isn't in any groups?
They have no custom role permissions, so all features that require permissions are greyed out or hidden. Make sure every member set to “Custom roles” is in at least one group that's assigned to a custom role.
Can I use both built-in and custom roles?
Yes. Members with the User, Admin, or Owner roles are unaffected by custom role permissions because they get their permissions from those roles directly. Only members set to Custom roles are controlled by the group-and-role system. This allows gradual migration.
What if a member is in two groups with different roles?
Permissions are additive. If any role in a member's chain grants a feature, they have it. You can't use a role to remove a permission granted by another role.
Can I use SCIM groups and manual groups together?
Yes. Both types can be assigned to custom roles. The difference is that SCIM group membership is managed in your identity provider, while manual group membership is managed in Claude's organization settings.
Are Owners and Primary Owners affected by custom role permissions?
No. Owners and Primary Owners always have full access to all features.
How does this work across parent and child organizations?
Groups and SCIM sync are managed at the parent organization level and shared across all child organizations. Role and spend limit assignments are configured independently in each child organization—changes in one child organization don't affect others. Group membership changes and SCIM resyncs propagate across all child organizations under the same parent.