Updates to Group REST APIs and Group Webhook Events

What is changing?

Confluence cloud is moving away from groupName towards groupId as the identifier for Groups. Two main changes may affect you.

  1. REST API - We will be exposing REST endpoints that will use groupId instead of groupName in the next two months. Once the new groupId APIs are available on Nov 16, 2020, we will start a 6 month deprecation for the APIs that use groupName. After this 6 month period, groupName will still be available but will no longer be immutable, so you will not be able to store it and rely on it being a stable identifier.

  2. Webhook Events - We will also be adding a new field groupId to the webhook events group_removed and group_created.

Why is it changing?

Currently since groupName is the identifier for groups it is immutable which means once a group is created there is no way to rename said group. A big reason we are making this change is so that going forward we can introduce the functionality to rename groups.

What do I need to do?



  1. Find out if you are storing groupName anywhere
  2. If not storing groupName, making this change is optional (there is still a small chance of getting a groupName and trying to make a new REST API call after the old groupName has been updated but this is a very unlikely case). Your team can make the decision, groupName will continue to be unique per organization but will no longer be immutable.
  3. If storing groupName, your team must update to use groupId instead because going forward groupName will no longer be immutable.

Webhook Events


  1. Determine if your team needs to make the switch to use the new field groupId instead of groupName.

By when do I need to do it?

Deprecation Date: May 17, 2021

REST APIs with groupName will still be available for use but groupName will no longer be immutable after this date. Please let us know if you have any concerns about this. We may adjust our timeline based on your feedback.


Will this also affect the REST APIs dealing with content restrictions and space permissions? Right now, giving a group permission is done by group name.

Generally very happy about this as we already store group IDs and currently have to resolve them to names first every time we want to do anything. :slight_smile:

What will happen to module conditions though? Are you going to add new conditions that allow you to check for group IDs there as well?


Yes, we will expose new APIs for restrictions and permissions wherever necessary too.

Let me discuss with the Connect team and get back to you.


Hi @jjohn were you able to discuss this with the Connect team? :slight_smile:


I saw that some of those endpoints were already added by now, that’s great. Have you got any update on the module conditions? :slight_smile:

1 Like

Hey Sven, I’m still looking into it because it involves both Jira and Confluence, will get back to you when I have a better understanding.

1 Like

Awesome, thanks for keeping us in the loop @jjohn ! :slight_smile:


Update: Sorry, not all the APIs will be ready by Nov 16 :unamused:. I will make a new post once all the new APIs are ready and the 6 month deprecation notice will only start from that date.


Is this Get Group Member endpoint deprecated for OAuth2.0(3LO)?

GET /wiki/rest/api/group/{groupId}/membersByGroupId

OAuth scope is not listed in the document and when trying to hit the API it gives 401, Unauthorized scope does not match error.

thanks for bringing this to our attention, that was a mistake on our end.

New API https://developer.atlassian.com/cloud/confluence/rest/api-group-group/#api-api-group-groupid-membersbygroupid-get
is supposed to replace the functionality of

We will be adding the missing OAuth scopes required: read:confluence-groups in the documentation, thanks for calling this out.

1 Like

I’m wondering if this change will also come to Jira APIs. Our app make use of both Confluence and Jira and when fetching the current user’s user groups through Jira we’re not getting the group id, just the name. We’re letting customers decide what user groups that can see certain content and we won’t be able to adjust for this Confluence update unless the ids are also returned from the Jira API.

Hi @jjohn , /rest/api/space/SPACEKEY?expand=permissions still doesn’t support groupId in the response. Will this be supported before the deprecation? Thanks!

1 Like

Hey Julia,

Jira and Confluence are doing this work separately and this change has not been planned for Jira yet so I unfortunately cannot give you a timeline for when to expect it.

Hey Kornesh,

Yes, it will be supported before the deprecation but we are currently blocked on some work that we need to do before we can include groupId in the response, we are hoping :crossed_fingers: to get unblocked sometime in January.

1 Like

Hey John,
moving to groupIds is a great step in the development. Is it also in your scope to use the id’s in the experimental apis, namely adding new permissions to groups via id?
Could you tell us if the experimental change are also included in the January patch? In the trello board someone has talked about updates being made in September and we haven’t gotten an update since then)

Hey Kilian,
Is there a specific API you are asking about? We are almost done with adding the groupId endpoints and I’m trying to confirm we have everything (we are still working on a few / rolling them out).

When group names become mutable does this also apply to the Confluence built-in special groups like ‘administrators’ and ‘confluence-users’? If so, will there be an API to get the ID of these groups?

1 Like

How does this work with the addon_property_contains_any_user_group condition?

Will this check on both group name and group id, or something else?

I’m currently matching this on group name, but will this change?

1 Like