Documentation

Resources

Get Support

Developer

Get Support

DOCUMENTATION

Cloud

Data Center

Resources

News and Updates

Get support

Developer

DOCUMENTATION

Cloud

Data Center

Resources

News and Updates

Get support

Cloud

Organizations REST API / Reference / REST API

Groups

Postman Collection

OpenAPI

Orgs Groups APIs

Operations

GET

Get groups in an organization

Returns a page of groups in an organization that match the supplied parameters.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

Query parameters

cursor

string

limit

integer

directoryIds

array<string>

accountIds

array<string>

groupIds

array<string>

resourceOwners

array<string>

resourceIds

array<string>

searchTerm

string

counts

object

sortBy

array<object>

Responses

Returned if the request is successful.

application/json

MultiDirectoryGroupPage

GET/v2/orgs/{orgId}/directories/{directoryId}/groups

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

{
  "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"
  }
}

POST

Create group

Create a group in a directory to manage app access and permissions for multiple users together.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

Request bodyapplication/json

name

string

Required

description

string

Responses

Success

POST/v2/orgs/{orgId}/directories/{directoryId}/groups

curl

Node.js

Java

Python

PHP

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>"
}'

GET

Get group role assignments

Returns a page of role assignments for a group that match the supplied parameters.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

groupId

string

Required

Query parameters

cursor

string

limit

integer

directoryIds

array<string>

resourceOwners

array<string>

resourceIds

array<string>

roleIds

array<string>

Responses

Returned if the request is successful.

application/json

MultiDirectoryGroupRoleAssignmentPage

GET/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/role-assignments

curl

Node.js

Java

Python

PHP

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'

200Response

{
  "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"
  }
}

POST

Grant access to group

Assign a role to a group to assign all members the same role.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

groupId

string

Required

Request bodyapplication/json

resourceId

string

Required

roleId

string

Required

Responses

Success

POST/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/role-assignments/assign

curl

Node.js

Java

Python

PHP

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>"
}'

POST

Remove access from group

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.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

groupId

string

Required

Request bodyapplication/json

resourceId

string

Required

roleId

string

Required

Responses

Success

POST/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/role-assignments/revoke'

curl

Node.js

Java

Python

PHP

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>"
}'

POST

Add user to group

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.

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.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

groupId

string

Required

Request bodyapplication/json

accountId

string

Required

Responses

Success

POST/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/memberships

curl

Node.js

Java

Python

PHP

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>"
}'

DEL

Remove user from group

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.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

groupId

string

Required

accountId

string

Required

Responses

Success

DEL/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/memberships/{accountId}"

curl

Node.js

Java

Python

PHP

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>'

GET

Get group details

Returns the details of a group.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

groupId

string

Required

Responses

Returned if the request is successful.

application/json

MultiDirectoryGroupDetails

GET/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}

curl

Node.js

Java

Python

PHP

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'

200Response

{
  "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"
    }
  }
}

DEL

Delete group

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.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

groupId

string

Required

Responses

Success

DEL/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request DELETE \
  --url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}' \
  --header 'Authorization: Bearer <access_token>'

GET

Get the count of groups in an organization

Returns the count of groups in an organization that match the supplied parameters.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

Query parameters

directoryIds

array<string>

accountIds

array<string>

groupIds

array<string>

resourceOwners

array<string>

resourceIds

array<string>

searchTerm

string

roleIds

array<string>

Responses

Returned if the request is successful.

application/json

object

GET/v2/orgs/{orgId}/directories/{directoryId}/groups/count

curl

Node.js

Java

Python

PHP

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'

200Response

1
2
3

{
  "count": 49
}

GET

Get group stats

Returns group stats for the organization.

Request

Path parameters

orgId

string

Required

directoryId

string

Required

Responses

Returned if the request is successful.

application/json

MultiDirectoryGroupStats

GET/v2/orgs/{orgId}/directories/{directoryId}/groups/stats

curl

Node.js

Java

Python

PHP

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'

200Response

{
  "types": [
    {
      "type": "TEAM",
      "count": 3
    },
    {
      "type": "GROUP",
      "count": 7
    },
    {
      "type": "USERBASE_GROUP",
      "count": 10
    }
  ],
  "totals": {
    "all": 10,
    "synced": 4,
    "managed": 6
  }
}

POST

Search for groups within an organizationDeprecated

This API is deprecated and will no longer work after June 30, 2026. Use the Get groups in an organization endpoint instead.

The API is available for customers using the new user management experience only. How the new user management experience works

Returns a list of groups within an organization, offering search functionality through multiple parameters for more precise results.

Request

Path parameters

orgId

string

Required

Request bodyapplication/json

groupIds

array<string>

groupNames

GroupNames

cursor

string

limit

integer

expand

array<string>

Responses

Organization found. Response contains group search results

application/json

GroupsSearchPage

POST/v1/orgs/{orgId}/groups/search

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/groups/search' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "limit": 20
}'

200Response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "example",
      "description": "example description"
    }
  ],
  "links": {
    "next": "MDNlZWRmNzMtMWYwMi00NGM5LWI4NjgtZGQ1NTIwMjIwYjhj",
    "self": "MDI0MzkwOGEtMmYyOC00NzgzLWI5YTktMDUwZTExNzJjZDU4"
  }
}

POST

Create groupDeprecated

This API is deprecated and will no longer work after June 30, 2026. Use the new Create group endpoint instead.

The API is available for customers using the new user management experience only. Learn more about the new user management experience.

This API will:

Create a group in the organization's directory.
Create a collection of users that you can use to easily manage permissions, content access, notification schemes, and roles.

The creation of new groups using existing group names is not permitted.

Learn the fastest way to call the API with a detailed tutorial.

Request

Path parameters

orgId

string

Required

Request bodyapplication/json

name

string

Required

description

string

Responses

Request to create group was successfully accepted and will be eventually created in the organization directory.

application/json

object

POST/v1/orgs/{orgId}/directory/groups

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/directory/groups' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "description": "<string>"
}'

200Response

{
  "message": "Group test-group was created",
  "groupId": "f29c72a8-7681-4ed0-8a2c-83372bf67437"
}

DEL

Delete groupDeprecated

This API is deprecated and will no longer work after June 30, 2026. Use the new Delete group endpoint instead.

The API is available for customers using the new user management experience only. Learn more about the new user management experience.

This API will:

Delete a group from the organization's directory.
Delete the permissions, content access, notification schemes, and roles granted to the users.

This API will not:

Delete groups that are synchronized through SCIM. To delete these groups, you will need to delete them within your external identity provider. Learn more about configuring user provisioning with an identity provider.
Delete a group if it’s marked as a default group.
Delete site-admin group and therefore revoke org-admin role from a user.
Delete a group if it contains users (unless forced).

Learn the fastest way to call the API with a detailed tutorial.

Request

Path parameters

orgId

string

Required

groupId

string

Required

Query parameters

forceIfNotEmpty

boolean

Responses

Group was successfully deleted from organization's directory.

application/json

object

DEL/v1/orgs/{orgId}/directory/groups/{groupId}

curl

Node.js

Java

Python

PHP

curl --request DELETE \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/directory/groups/{groupId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

1
2
3

{
  "message": "Group 0980d761-fce5-4ea1-83e4-9cc8f5db92ae was removed"
}

POST

Assign roles to a groupDeprecated

This API is deprecated and will no longer work after June 30, 2026. Use the Grant access to group endpoint instead.

The API is available for customers using the new user management experience only.

Assign roles that grant product access to groups. Please note that this operation adheres to eventual consistency, and it might take up to 30 seconds for changes to take effect.

Request

Path parameters

orgId

string

Required

groupId

string

Required

Request bodyapplication/json

roleAssociations

array<RoleAssociation>

Required

Responses

Roles were successfully added to the group

application/json

object

POST/v1/orgs/{orgId}/directory/groups/{groupId}/roles/assign

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/directory/groups/{groupId}/roles/assign' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "roleAssociations": [
    {
      "resource": "ari:cloud:jira::site/70ef3a32-d0da-4e09-b35e-0109f91969c3",
      "role": "atlassian/user"
    }
  ]
}'

202Response

1
2
3

{
  "message": "Group 12345 added Roles. ROLE `user` for RESOURCE `ari:cloud:identity::group/test-group-uuid1` and ROLE `user-access-admin` for RESOURCE `ari:cloud:identity::group/test-group-uuid2` is in progress. Changes may take up to 30 seconds to reflect."
}

POST

Revoke roles from a groupDeprecated

This API is deprecated and will no longer work after June 30, 2026. Use the Remove access from group endpoint instead.

The API is available for customers using the new user management experience only.

Revoke roles that provide product access to groups. It's important to note that this operation follows eventual consistency principles and may require up to 30 seconds to take effect.

Request

Path parameters

orgId

string

Required

groupId

string

Required

Request bodyapplication/json

roleAssociations

array<RoleAssociation>

Required

Responses

Roles were successfully removed from the group

application/json

object

POST/v1/orgs/{orgId}/directory/groups/{groupId}/roles/revoke

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/directory/groups/{groupId}/roles/revoke' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "roleAssociations": [
    {
      "resource": "ari:cloud:jira::site/70ef3a32-d0da-4e09-b35e-0109f91969c3",
      "role": "atlassian/user"
    }
  ]
}'

202Response

1
2
3

{
  "message": "Group 12345 revoked Roles. ROLE1 for RESOURCE1 and ROLE2 for RESOURCE2 is in progress. Changes may take up to 30 seconds to reflect."
}

POST

Add user to groupDeprecated

This API is deprecated and will no longer work after June 30, 2026. Use the new Add user to group endpoint instead.

The API is available for customers using the new user management experience only. Learn more about the new user management experience.

This API will:

Add user to a group.
Assign multiple permissions to user at once.
Easily manage permissions, content access, notification schemes, and roles.

This API will not:

Make modifications to group memberships that are synchronized through SCIM. To make changes to these memberships, you will need to modify them within your external identity provider. Learn more about configuring user provisioning with an identity provider.
Add a user to a group that gives access to a product which is breaching it's license limit.
To make these changes, you will need to remove users from the group or suspend users that are in the group first.
You can also manage your subscription for the breaching product to increase your license limits.
Add a user to any group when your organisation has too many products that are breaching their license limits.

Learn the fastest way to call the API with a detailed tutorial.

Request

Path parameters

orgId

string

Required

groupId

string

Required

Request bodyapplication/json

account_id

string

Required

Responses

User was successfully added to the group in the organization directory.

application/json

object

POST/v1/orgs/{orgId}/directory/groups/{groupId}/memberships

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/directory/groups/{groupId}/memberships' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "account_id": "<string>"
}'

200Response

1
2
3

{
  "message": "User 637194fa77acd224b33bfae3 was added to group 9233fb03-53cc-4463-9698-047aedbffb5c"
}

DEL

Remove user from groupDeprecated

This API is deprecated and will no longer work after June 30, 2026. Use the new Remove user from group endpoint instead.

The API is available for customers using the new user management experience only. Learn more about the new user management experience.

This API will:

Remove user from a group.
Remove multiple permissions for user at once.
Easily manage permissions, content access, notification schemes, and roles.

This API will not:

Make modifications to group memberships that are synchronized through SCIM. To make changes to these memberships, you will need to modify them within your external identity provider. Learn more about configuring user provisioning with an identity provider.
Modify site-admin group and therefore revoke org-admin role from a user.

Learn the fastest way to call the API with a detailed tutorial.

Request

Path parameters

orgId

string

Required

groupId

string

Required

accountId

string

Required

Responses

User was successfully removed from the group in the organization directory.

application/json

object

DEL/v1/orgs/{orgId}/directory/groups/{groupId}/memberships/{accountId}

curl

Node.js

Java

Python

PHP

curl --request DELETE \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/directory/groups/{groupId}/memberships/{accountId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

1
2
3

{
  "message": "User 63ec0aa0c5061c632c0cddde was removed from group fca77b90-a2a9-4385-961b-1377b3dbeb0b"
}