Cloud

Organizations REST API / Reference / REST API

Directory

Org Directory APIs

Operations

GET

User’s last active dates

Additional response parameters of the API (for e.g., added_to_org) are available only to customers using the new user management experience. Learn more about the new user management experience.

Specifications:

Return a user’s last active date for each product listed in Atlassian Administration.
Active is defined as viewing a product's page for a minimum of 2 seconds.
The data for the last activity may be delayed by up to 24 hours.
If the user has not accessed a product, the product_access response field will be empty.

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

Request

Path parameters

orgId

string

Required

accountId

string

Required

Query parameters

cursor

string

Responses

Successful operation

application/json

UserProductAccessActivityPage

GET/v1/orgs/{orgId}/directory/users/{accountId}/last-active-dates

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/directory/users/{accountId}/last-active-dates' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

{
  "data": {
    "product_access": [
      {
        "id": "<string>",
        "key": "jira-software",
        "last_active": "<string>"
      }
    ],
    "added_to_org": "<string>"
  },
  "links": {
    "next": "<string>"
  }
}

DEL

Remove user access

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

Specifications:

Remove user access to products listed in Atlassian Administration.
Remove users from Users and Groups in Directory.
Make product licenses available for active users.

The users are not removed immediately; instead, they are placed in a queue for deletion. Please note that it may take some time for all users to be completely removed.

Users with emails whose domain is claimed can still be found in Managed accounts in Directory.

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

Request

Path parameters

orgId

string

Required

accountId

string

Required

Responses

User access removed from organization. Everything went fine, nothing to return. The users are not removed immediately; instead, they are placed in a queue for deletion. Please note that it may take some time for all users to be completely removed.

DEL/v1/orgs/{orgId}/directory/users/{accountId}

curl

Node.js

Java

Python

PHP

1
2
3

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

POST

Suspend user access

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

Specifications:

Suspend user access to products listed in Atlassian Administration.
Make product licenses available for active users.
Maintain respective users in Groups for easy restoration.

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

Request

Path parameters

orgId

string

Required

accountId

string

Required

Responses

User was successfully suspended in the organization directory.

application/json

object

POST/v1/orgs/{orgId}/directory/users/{accountId}/suspend-access

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/directory/users/{accountId}/suspend-access' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

1
2
3

{
  "message": "Access to organization 6665kc2j-4644-14k8-j32c-68cc0b1d15b8 was suspended for user 637194fa77acd224b33bfae3"
}

POST

Restore user access

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

This API will:

Restore access of an existing user to products listed in Atlassian Administration.
Retract the suspend user action.

This API will not:

Restore access to a user when they have 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.
Restore access to any user 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

accountId

string

Required

Responses

User's access is successfully restored in the organization directory.

application/json

object

POST/v1/orgs/{orgId}/directory/users/{accountId}/restore-access

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/directory/users/{accountId}/restore-access' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

1
2
3

{
  "message": "Access to organization 6665kc2j-4644-14k8-j32c-68cc0b1d15b8 was restored for user 637194fa77acd224b33bfae3"
}

POST

Create group

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 group

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

Add user to group

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 group

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

POST

Invite user to orgExperimental

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

This API is in limited availability and access. The development, release, and timing of any features or functionality described herein remain at the sole discretion of Atlassian and are subject to change. Please reach out to Atlassian support to get access to this API.

This API will:

invite user to org and add them to the directory
assign a role for a given resource
send email if the sendNotification field is set true with optional custom message for the email

This API will not:

add users to group

Request

Path parameters

orgId

string

Required

Request bodyapplication/json

email

string

Required

permissionRule

RoleAssociation

sendNotification

boolean

notificationText

string

Responses

Invitation successfully sent

application/json

array<string>

POST/v1/orgs/{orgId}/users/invite

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/users/invite' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "<string>",
  "permissionRule": {
    "resource": "ari:cloud:jira::site/70ef3a32-d0da-4e09-b35e-0109f91969c3",
    "role": "atlassian/user"
  },
  "sendNotification": true,
  "notificationText": "<string>"
}'

202Response

1
2
3

[
  "619034:4eb0cd3f-3cb6-4561-8d6a-0546e66cab3d"
]

POST

Assign roles to a groupExperimental

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

This API is in limited availability and access. The development, release, and timing of any features or functionality described herein remain at the sole discretion of Atlassian and are subject to change. Please reach out to Atlassian support to get access to this API.

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 groupExperimental

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

This API is in limited availability and access. The development, release, and timing of any features or functionality described herein remain at the sole discretion of Atlassian and are subject to change. Please reach out to Atlassian support to get access to this API.

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

Grant user accessExperimental

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

This API is in limited availability and access. The development, release, and timing of any features or functionality described herein remain at the sole discretion of Atlassian and are subject to change. Please reach out to Atlassian support to get access to this API.

This API can be used to grant Platform Roles to a user.

Request

Path parameters

orgId

string

Required

userId

string

Required

Request bodyapplication/json

role

string

Required

resource

string

Responses

Role Assigned Successfully.

POST/v1/orgs/{orgId}/users/{userId}/roles/assign

curl

Node.js

Java

Python

PHP

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

POST

Revoke user accessExperimental

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

This API is in limited availability and access. The development, release, and timing of any features or functionality described herein remain at the sole discretion of Atlassian and are subject to change. Please reach out to Atlassian support to get access to this API.

This API can be used to revoke Platform Roles from a user.

Request

Path parameters

orgId

string

Required

userId

string

Required

Request bodyapplication/json

role

string

Required

resource

string

Responses

Role Revoked Successfully.

POST/v1/orgs/{orgId}/users/{userId}/roles/revoke

curl

Node.js

Java

Python

PHP

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