Cloud

Organizations REST API / Reference / REST API

Directory

Org Directory APIs

Operations

GET/v1/orgs/{orgId}/directory/users/{accountId}/last-active-dates DEL/v1/orgs/{orgId}/directory/users/{accountId}POST/v1/orgs/{orgId}/directory/users/{accountId}/suspend-access POST/v1/orgs/{orgId}/directory/users/{accountId}/restore-access POST/v1/orgs/{orgId}/directory/groups DEL/v1/orgs/{orgId}/directory/groups/{groupId}POST/v1/orgs/{orgId}/directory/groups/{groupId}/memberships DEL/v1/orgs/{orgId}/directory/groups/{groupId}/memberships/{accountId}

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.

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.

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