|
👋 Update 23 May 2025
The steps mentioned in this article are no longer necessary to retrieve the Directory ID. We have now made available an API endpoint that queries the Directory ID more easily.
You can find the endpoint here.
The only information required are the Org ID and the API Key. Both can be extracted from admin.atlassian.com > Security > API Keys.
|
|
⚠️ This article does not apply for retrieving SCIM Directory IDs.
|
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.
" data-emoji-text="
">" data-testid="image-emoji-" data-emoji-type="image">
" data-emoji-id="atlassian-warning" data-emoji-text="" data-vc="emoji" /> 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 (<a href="https://admin.atlassian.com/o/%7Borganization_ID%7D/" rel="noopener nofollow noreferrer" target="_blank">https://admin.atlassian.com/o/{organization_ID}/</a>).
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:
"546b083f-5f25-4232-a044-3196d0c77ce3"
This ID 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!
