FAQ: Role-based access in Confluence
This page answers frequently asked questions for Confluence sites transitioning from individual space permissions to role-based access. The transition guidance on this page doesn’t apply to sites already using role-based access only.
For step-by-step guidance, refer to Roles central and planning your transition and Custom access and how to transition to roles.
What is role-based access in Confluence?
Role-based access is a way to manage space access by assigning a predefined set of permissions instead of managing each permission individually.
Default roles
Confluence provides 4 default roles:
Role | What the role allows |
|---|---|
Admin | Manages everything in the space |
Manager | Manages people and content, but not space settings |
Collaborator | Creates and edits content |
Viewer | Views and comments on content |
Custom roles
Confluence admins can create custom roles for recurring access needs that the default roles don’t support.
Read about roles and their permissions
Why did roles become available if my organization didn’t opt in?
Roles are rolling out to Confluence Cloud sites as part of the general availability release.
Existing sites first enter a transition period in which roles and existing permission combinations can work side by side. This lets admins start using roles without immediately changing anyone’s access.
What changes when roles become available on my site?
Confluence preserves existing access. People, groups, teams, guests, apps, and user classes that don’t yet have a role continue to receive their existing permissions through Custom access.
Admins can review that access and transition it to a default or custom role when they’re ready.
How do I know whether roles are available on my site?
Confluence admins can open the permissions settings. If roles are available, the settings include role-management areas such as Space roles, System operations, and Roles central.
Can roles be enabled for only one space?
No. Roles become available at the Confluence site level, not one space at a time.
What is transition mode?
Transition mode is a temporary state in which a site supports both existing permission combinations and roles.
It gives admins time to:
Review current access
Decide which default roles to use
Create custom roles for recurring access needs
Update default access for new spaces
Transition Custom access to roles across all spaces
This coexistence is temporary. Before the transition window ends, admins should review remaining Custom access and assign appropriate roles.
What is Custom access?
Custom access means that a person, group, team, guest, app, or user class still has an existing combination of individual permissions instead of an assigned role.
Custom access preserves existing permissions during the transition. It doesn’t mean that the access comes from a custom role.
More about Custom access and how to transition to roles
What’s the difference between Custom access and a custom role?
| Custom access | Custom role |
|---|---|---|
What it is | An existing combination of individual permissions that Confluence preserved during the move to roles | A named, reusable set of permissions |
How it’s created | Appears automatically when existing access doesn’t yet have a role | Created by a Confluence admin |
How it’s used | Temporarily preserves access during the transition | Can be assigned repeatedly when the default roles don’t support a recurring access need |
Space admins can assign available custom roles but can’t create or edit them.
How to create and manage custom roles
Do existing permission combinations automatically map to roles?
No. Confluence initially preserves existing permission combinations as Custom access instead of choosing a role automatically.
This prevents unintended changes and lets admins decide which default or custom role represents each access pattern.
What is role-based access only mode?
Role-based access only mode is the final state in which admins manage space access through default and custom roles. Legacy granular permissions and Custom access are no longer available for ongoing access management.
Admins can continue to manage default roles, custom roles, system operations, and role assignments.
New Confluence Cloud sites start in role-based access only mode.
How should I plan the transition?
Use Roles central to understand the transition steps, review your site’s progress, and identify access that still needs to move to roles.
A typical transition includes the following steps:
Review the transition information in Roles central.
Compare existing access patterns with the default roles.
Create custom roles for recurring needs the default roles don’t support.
Review remaining access and your configured fallback role before the transition window ends.
Plan and track your transition in Roles central
How long do I have to complete the transition?
Confluence admins can view the transition date for their site in Roles central.
What happens if I don’t transition all Custom access before the transition window ends?
When the transition window ends, Confluence applies your configured fallback role to people, groups, teams, guests, and user classes that still have Custom access.
Before the window ends:
Review the permissions included in the fallback role
Transition access that needs a different role
Preview the effect of bulk changes before applying them
Use the audit log to review completed changes
How to configure a fallback role and complete your transition
Can I return to the legacy permissions experience?
No. After a site moves to role-based access only, legacy granular permissions and Custom access are no longer available. Default and custom roles become the way to manage space access.
If roles cause unexpected behavior that prevents you from managing access, contact Atlassian Support and include:
The affected site and space
The person, group, team, guest, app, or user class involved
The access you expected
What happened instead
The steps you took before the problem occurred
How should I decide which roles to use?
Start by comparing your existing permission combinations with the default roles. If a default role supports the access pattern, use it.
Create a custom role when your organization has a recurring access need that the default roles don’t support. Design custom roles around job responsibilities and governance needs instead of recreating every historical permission variation.
How many custom roles can I create?
A Confluence Cloud site can have up to 10 custom roles.
Use custom roles for meaningful, reusable access patterns rather than one-off exceptions. If you need many custom roles, consider whether you can simplify or combine similar access patterns.
Create and manage custom roles
Who can create and assign custom roles?
Confluence admins can create, edit, and delete custom roles.
Space admins can assign available default and custom roles within the spaces they manage, but they can’t create or edit custom roles.
Can I test roles in a sandbox before using them in production?
If your plan includes a Confluence sandbox, you can use it to test custom roles, transition plans, and administrator workflows before making large-scale production changes.
Can I continue managing access through groups?
Yes. Roles don’t replace groups.
Groups collect people together. Roles define what those people can do in a space. You can assign a role to a group so group membership continues to control who receives access while the role controls the permission set.
After confirming that people receive the access they need through groups, you can use the transition tools to remove unnecessary direct access and transition group access to roles.
What happens when someone receives access from multiple sources?
Space access is additive. A person can receive access directly and through groups, teams, or user classes. Their effective access combines all of those sources.
The Users table shows each source of access. Review all sources before removing or reducing access because changing one assignment might not remove access granted through another source.
Learn how to troubleshoot access from multiple sources
What are user classes?
User classes let admins grant a role to a broad, automatically maintained set of people, such as All Confluence users or All Confluence admins.
Use user classes when the same access should apply to everyone in that class. Membership stays current as people gain or lose access to Confluence.
Can someone assign a role with more permissions than they have?
No. Confluence prevents people who manage access from assigning a role that contains permissions they don’t hold. They also can’t change an existing space admin’s access unless they have the required permissions.
These safeguards prevent someone from increasing their own access or another person’s access beyond what they’re allowed to grant.
Can I disable a default role?
Yes. Confluence admins can disable a default role when it doesn’t fit their organization’s access model.
If a system operation uses the role, update that operation before disabling it. If people already hold the role, Confluence lets you replace the role across all spaces or remove their access.
After you disable the role, it no longer appears in role selectors and can’t be assigned until a Confluence admin restores it.
What are system operations?
System operations are Confluence-managed actions that automatically assign access in specific situations, such as guest access or space ownership flows.
Where an operation is configurable, Confluence admins can choose which role the operation assigns or configure it not to assign access.
Learn about managing system operations
How do migrations interact with roles?
Migration behavior depends on the source site, destination site, migration method, and the access mode of each site. Some migration flows preserve imported permissions as Custom access so that access isn’t lost.
Review What to expect from roles when migrating Confluence data and the documentation for your migration method before migrating between sites that use legacy permissions, transition mode, or role-based access only.
Should I transition to role-based access before a migration?
The appropriate sequence depends on your migration method, timing, and access model. Imported permission-based access may need to be transitioned after the migration.
For a complex migration, review the current migration documentation and plan the sequence with Atlassian Support or your migration contact instead of changing modes immediately before the migration.
Which APIs should integrations use for role-based access?
Role-based access provides V2 APIs for managing space role assignments. Update scripts and integrations that assign individual space permissions so they use the supported role APIs before your site moves to role-based access only.
View Confluence V2 API documentation for space roles
Why did a role assignment change back to Custom access?
An external script, integration, or legacy API might have updated the underlying individual permissions directly. When this happens, Confluence may display the access as Custom access again.
Review scripts and integrations that manage space permissions and update them to use the supported role APIs.
Was this helpful?