Guide: Find the directory ID for your userbase

[#1]

Description

Atlassian recently introduced new organization REST APIs. These APIs let you retrieve users from your organization and manage their access to your cloud products. This can help you manage users and access more efficiently.

Certain endpoints require a path parameter known as directoryId. The directory ID is a unique identifier for a specific userbase and is composed of an alphanumerical value.

Example endpoint: Get users in an organization

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

 You’ll notice the directoryId path parameter in the above URL.

The directoryId is not the same as a SCIM directory ID, which is used to provision users and groups from an identity provider to Atlassian. About the user provisioning REST API.

Instructions

There is currently no way to retrieve the directory ID through Atlassian Administration (admin.atlassian.com).

Instead, you can retrieve the directory ID through the GET list of workspaces endpoint:

curl --request POST \
  --url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/workspaces' \
  --header 'Authorization: Bearer ' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

A workspace is an instance of an Atlassian product. When you add a new product to your organization, a new workspace is created.

The endpoint on the documentation includes a cursor field in the request body (located under data), for pagination purposes. I’ve excluded this field from the above example, as it is not mandatory.

To run the GET list of workspaces endpoint, you’ll need an API key and your organization ID. An organization admin can generate both of these from admin.atlassian.com > Settings > API Keys. You can also get your organization ID from the URL when you’re in Atlassian Administration (https://admin.atlassian.com/o/{organization_ID}/).

With the API key and organization ID, you’ll be able to run the endpoint. The response includes several fields and values related to your sites and products. One of these fields is called ‘directory’ which appears as follows:

"ari:cloud:identity::userbase/546b083f-5f25-4232-a044-3196d0c77ce3"

The value following ari:cloud:identity::userbase/ represents the directory ID for your userbase. You can use this ID in any endpoint where it is required.

We plan to release a specific endpoint to retrieve directory IDs soon. Thank you for your patience!