Bulk get groups API enhanced to support group lookups based on access type

What is changing?

Jira is making the transition from using groupName to groupId as the identifier for groups. To support this change, we are modifying our APIs that have group name fields. The groupName is no longer going to be immutable and Jira should start referring to the group via external groupId as the immutable reference.

The marketplace apps having hardcoded references to group names, particularly for default groups (for example, site-admins, jira-admins-<tenantName>) in their configurations may be impacted. We will enhance the existing bulk get groups (GET /rest/api/3/group/bulk) API to support fetching groups by their access type (for example, fetching site-admins group by site-admin access type)

Why is it changing?

We are aiming to migrate site-level userbases to the organisation level. The customers having multiple sites in the same organisation need to have their userbases merged. During userbase merges, there can be conflicts in group names across sites in an organisation. As a consequence, the ability to rename groups in Jira is essential to avoid any permission escalations.

Give me some technical details!

We currently have an API to get groups: bulk get groups (GET /rest/api/3/group/bulk). We are enhancing this API by adding a new optional query parameter named accessType that will return only groups with a specific type of permission based on the accessType provided:

GET /rest/api/3/group/bulk?accessType=<ACCESSTYPE>
Valid values for ACCESSTYPE: site-admin, admin, user

GET /rest/api/3/group/bulk?accessType=site-admin
Returns list of groups that have site administration access

GET /rest/api/3/group/bulk?accessType=admin
Returns list of groups that have Jira administration access

GET /rest/api/3/group/bulk?accessType=user&applicationKey=jira-software
Returns list of groups that have Jira software access

What do I need to do?

If your apps are backed by lookup on hardcoded group names (for example, site-admins, jira-admins-<tenantName>). it is recommended to start using the above API to get groups, in order to ensure your app continues to work for all customers.

We will keep you updated on any further changes and actions required related to this change.

Please feel free to reply to this thread in case of any queries or suggestions.

3 Likes

Hello @SwagataKundu,
Thanks for the heads-up! As far as I can tell, the new accessType parameter has not been rolled out yet, correct? At least I cannot see it in the documentation.

Could you please let us know in here once the new API is live?

Thanks!

Hi @ben2,
We have started rolling out the change for the accessType parameter and we plan to roll it out completely by 14 September, 2022.