Orgs Groups APIs
Return a page of groups in an organization that match the supplied parameters.
Use searchTerm for free-text search across group names. Filter by IDs, role assignments, resources, members, or specific group identifiers using the corresponding request fields. Use the expand field to include additional fields such as counts.resources and counts.users in the response.
string
Requiredstring
Requiredstring
integer
array<GroupSortBy>
array<string>
array<string>
array<string>
array<string>
array<string>
string
array<string>
Success
1
2
3
4
5
6
7
8
9
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/search' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"searchTerm": "engineering",
"limit": 20
}'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"data": [
{
"id": "12345678-1234-1234-1234-123456789012",
"name": "jira-administrators",
"description": "This group provides admin access to Jira.",
"directoryId": "12345678-1234-1234-1234-123456789012",
"managementAccess": {
"deletable": true,
"modifiable": true,
"readable": true
},
"externalSynced": true,
"managedBy": "external",
"counts": {
"users": 10,
"resources": 109
},
"links": {
"self": "ECg53CukK1twBo0LK1u9nw"
}
}
],
"links": {
"self": "ObSbZxpM1f1fzia2_GnuJw",
"prev": "LIZFEbzCT2pCCkQhPIUgIQ",
"next": "kloHX1ZQVasDAkx_P48NYQ"
}
}Returns a page of role assignments for a group that match the supplied parameters.
Authorization scopes required: read:groups:admin
string
Requiredstring
Requiredstring
Requiredstring
integer
array<string>
array<string>
array<string>
array<string>
Returned if the request is successful.
1
2
3
4
curl --request GET \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/role-assignments' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"data": [
{
"resourceId": "ari:cloud:jira-core::site/1",
"resourceOwner": "jira-core",
"defaultRole": "atlassian/org-admin",
"roles": [
"atlassian/org-admin",
"atlassian/site-admin",
"atlassian/user-access-admin"
]
}
],
"links": {
"self": "ObSbZxpM1f1fzia2_GnuJw",
"prev": "LIZFEbzCT2pCCkQhPIUgIQ",
"next": "kloHX1ZQVasDAkx_P48NYQ"
}
}Assign a role to a group to assign all members the same role.
string
Requiredstring
Requiredstring
Requiredstring
Requiredstring
RequiredSuccess
1
2
3
4
5
6
7
8
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/role-assignments/assign' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"resourceId": "<string>",
"roleId": "<string>"
}'Revoke a role from a group to remove access to an app from all members. A member can still access the app if they’re in another group that grants access to the same app.
string
Requiredstring
Requiredstring
Requiredstring
Requiredstring
RequiredSuccess
1
2
3
4
5
6
7
8
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/role-assignments/revoke' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"resourceId": "<string>",
"roleId": "<string>"
}'Add a user to a group. This gives the user the same app access and permissions as the group. The user must be in the same directory as the group.
Note: Adding a user to the org-admin group through this API will return an error after the Units rollout. The org-admin group will no longer grant organization admin access after the rollout. To grant organization admin, use the Assign organization-level role endpoint instead. This applies to all organizations, not just unit organizations.
You can’t add a user to a group synced from an identity provider. Manage this group in your identity provider instead.
You can’t add a user to a group if you’ve exceeded your user limit for an app that the group grants access to. Increase your user limit or suspend another user from the app first.
string
Requiredstring
Requiredstring
Requiredstring
RequiredSuccess
1
2
3
4
5
6
7
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/memberships' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"accountId": "<string>"
}'Remove a user from a group. This removes any app access and permissions granted by this group, but the user may still be in other groups that grant the same app access and permissions.
string
Requiredstring
Requiredstring
Requiredstring
RequiredSuccess
1
2
3
curl --request DELETE \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/memberships/{accountId}' \
--header 'Authorization: Bearer <access_token>'Returns the details of a group.
string
Requiredstring
Requiredstring
RequiredReturned if the request is successful.
1
2
3
4
curl --request GET \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"data": {
"id": "12345678-1234-1234-1234-123456789012",
"name": "jira-administrators",
"description": "This group provides admin access to Jira.",
"directoryId": "12345678-1234-1234-1234-123456789012",
"managementAccess": {
"deletable": true,
"modifiable": true,
"readable": true
},
"externalSynced": true,
"managedBy": "external",
"counts": {
"users": 10,
"resources": 109
},
"links": {
"self": "ECg53CukK1twBo0LK1u9nw"
}
}
}Delete a group from a directory if you don’t need this group anymore. This removes any app access and permissions granted by this group from all members. A member can still access an app if they’re in another group that grants access to the same app.
string
Requiredstring
Requiredstring
RequiredSuccess
1
2
3
curl --request DELETE \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}' \
--header 'Authorization: Bearer <access_token>'Returns the count of groups in an organization that match the supplied parameters.
string
Requiredstring
Requiredarray<string>
array<string>
array<string>
array<string>
array<string>
string
array<string>
Returned if the request is successful.
1
2
3
4
curl --request GET \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/count' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
{
"count": 49
}Returns group stats for the organization.
string
Requiredstring
RequiredReturned if the request is successful.
1
2
3
4
curl --request GET \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/stats' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"types": [
{
"type": "TEAM",
"count": 3
},
{
"type": "GROUP",
"count": 7
},
{
"type": "USERBASE_GROUP",
"count": 10
}
],
"totals": {
"all": 10,
"synced": 4,
"managed": 6
}
}This API is deprecated and will no longer work after June 30, 2027. Use the Search for groups in an organization endpoint instead.
Returns a page of groups in an organization that match the supplied parameters.
Authorization scopes required: read:groups:admin
string
Requiredstring
Requiredstring
integer
array<string>
array<string>
array<string>
array<string>
array<string>
string
object
array<object>
Returned if the request is successful.
1
2
3
4
curl --request GET \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"data": [
{
"id": "12345678-1234-1234-1234-123456789012",
"name": "jira-administrators",
"description": "This group provides admin access to Jira.",
"directoryId": "12345678-1234-1234-1234-123456789012",
"managementAccess": {
"deletable": true,
"modifiable": true,
"readable": true
},
"externalSynced": true,
"managedBy": "external",
"counts": {
"users": 10,
"resources": 109
},
"links": {
"self": "ECg53CukK1twBo0LK1u9nw"
}
}
],
"links": {
"self": "ObSbZxpM1f1fzia2_GnuJw",
"prev": "LIZFEbzCT2pCCkQhPIUgIQ",
"next": "kloHX1ZQVasDAkx_P48NYQ"
}
}Create a group in a directory to manage app access and permissions for multiple users together.
string
Requiredstring
Requiredstring
Requiredstring
Success
1
2
3
4
5
6
7
8
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"name": "<string>",
"description": "<string>"
}'Rate this page: