- Changed date from August 2nd to August 9th for changing the default group names for new customers
- Added date August 5th 2021 for when we will enhance this API by adding a new optional query parameter named
- Added new section titled Testing Notes
A group is a collection of users. Administrators create groups so that the administrator can assign permissions to a number of people at once. For example, it is quicker to give group ‘X’ access to Jira Software, rather than giving every team member access individually. In cloud, each group needs to be uniquely named. A user can be a member of multiple groups. Groups are particularly important as they are used to:
- Control users access to a product instance.
- Restrict which users have access to content within a product instance, like restricting access to a Confluence space or page, or access to a Jira Software project.
- Enable features for groups of users within a Jira product or Confluence, like editing, commenting or workflows.
Today, our APIs are keyed off group name and some apps may be expecting certain group names to always exist, such as the default groups that Atlassian creates when a new product is provisioned. But these default groups don’t always exist.
Groups have always been able to be altered by customers. They can create new groups, delete existing groups, and alter which products those groups get access to. So a customer may start off with two groups called
confluence-users , that grant access to Jira Software and Confluence. But they could end up with a single group called
all-staff that grants access to both Jira Software AND Confluence.
We’ll be changing the default group names for new customers on August 9th 2021, so we can better disambiguate groups for customers who want to see all groups in a single list, across all their products. To do this, we’ll attach the site name to the current default group names, e.g. for the site Acme Test, the default confluence group name will be
confluence-users-acmetest . Existing customers will not have their groups altered before February 1st 2022.
We’re altering our architecture to allow a single userbase at the Organisation level to serve a number of different products, on multiple sites. This requires us to update our group names to ensure they’re still unique in the future.
As a side note; We’re also working towards a long term goal of allowing customers to change their group names, rather than having to create a new one and delete the old one. This is something that our customers have wanted for about ~18 years . Once this work is complete, customers will be able to change any group name they like. But, we have many months of work ahead of us before this is in customers hands.
We currently have an API to get groups:
GET /wiki/rest/api/group (see The Confluence Cloud REST API for more details). On August 5th 2021, we will enhance this API by adding a new optional query parameter named
accessType that will return only groups with that type of permission:
GET /wiki/rest/api/group?accessType=<ACCESS_TYPE>(ACCESS_TYPE must be
- return list of groups that have product admin access to Confluence
- return list of groups that have use access to Confluence
- return list of groups that have admin access to the site or organisation
We strongly encourage using this API going forward since it’s unreliable to lookup static group names today, and may result in more unexpected results in the future.
Our team will have more information on when this API will be available around October 2021.
If your apps search for groups based on group name, you should instead consume the above API to get groups, in order to ensure your app works for all customers.
If do you have customers experiencing issues with your app due to unexpected group names, they are always able to manually create any group name you need them to and apply the correct product access permissions to it.
You can test this API by: