Guide: Find the directory ID for your userbase

[#1]

👋 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.

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:

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

[Krystien Hart]

Hi @Kenneth De Coster , 

Can you PLEASE make an effort to link this information in the KB articles that refer to directoryID? There is absolutely nothing in ANY PART of the Jira KB detailing this process, which is incredibly frustrating since, as youve said, There is currently no way to retrieve the directory ID through Atlassian Administration.

Thanks,

[Kenneth De Coster]

Hello @Krystien Hart,

Thank you for your effort. I'll gladly help with making sure this is visible on other KB articles! The only documentation I know of which refers to the directoryId is on our REST API docs. Do you have any particular articles where you've seen the directoryId mentioned? 

[Kenneth De Coster]

👋 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.

[Pascal BELLEBOUCHE]

Just tried the endpoint to get directoryId, but it gives 404 error. I tried with several orgs but no success.

Is there any known issues/limitations here ?

[Kenneth De Coster]

@Pascal BELLEBOUCHE, 

Are you referring to the Directory ID Endpoint? Can you share the error you are seeing?

[Negin Nafari]

Hi,

Just an FYI, we tried fetching the directory ID via the endpoint mentioned here:

https://developer.atlassian.com/cloud/admin/organization/rest/api-group-directory/#api-v2-orgs-orgid-directories-get

It is for sure giving us an ID and the correct name of the Directory ID.

However, when we are using this ID in other endpoints (https://developer.atlassian.com/cloud/admin/user-provisioning/rest/api-group-users/#api-scim-directory-directoryid-users-userid-patch) we get an error (not sure if it was out of scope or unauthorized and dont really want to test this again)

Anyways, for us the directory ID that was working properly on the above mentioned endpoint, was the one mentioned in our Identity provider (and not output of what is mentioned in this post) :/

Hopefully this will help some other people who are stuck :)

[Kenneth De Coster]

Hello @Negin Nafari

Thank you for your comment! The Directory ID for the userbase is not the same as the SCIM Directory ID, those are two separate userbases (perhaps this isn't clear on this article). The endpoint you are sharing, is one for User Provisioning and uses a SCIM Directory. The endpoint mentioned in my update does not work for SCIM directories. 

Retrieving the SCIM DB is a bit tricky. Support can provide it for you in case you can share the Org ID. You can also find it on your IdP where you configured User Provisioning, together with the API Key as the Base URL (looks like https://api.atlassian.com/scim/directory/{SCIM_DIRECTORY_ID}).

[Negin Nafari]

Oh I see, thanks! Yes we needed the SCIM user directory and as you mentioned we saw this info in our IdP, so all good here.

We are now facing a separate issue: when a user is deactivated in our IdP, they are not being removed from their corresponding groups in Atlassian. Our IdP logs confirm that the deactivation and group removal commands are being processed correctly on our end.

We know that there are endpoints supporting removing users from SCIM groups, but we would prefer not building an automation since we already have the Atlassian Guard

This public Jira work item seems to describe the same problem, although its not a technical: https://jira.atlassian.com/browse/AX-104.

We would appreciate any feedback or guidance you can provide. If this isn't the correct forum for this discussion, please let us know where we should direct our inquiry.

[Kenneth De Coster]

Hi Negin,

I think I found your case with our Support team (PCS-441552) and the affected user. Looking at the SCIM DB, it never got the command for updating the group memberships, we only got the Deactivation command. So in order for it to update on Atlassian, Okta must first push it to the SCIM DB.

This may happen if you first deactivate a user and then remove them from the groups. From the following Okta documentation, it sounds like:
"Users deactivated in Okta are not pushed to the downstream app. They must be reactivated, and then the group must be pushed. If the inactive user is part of more than one group, they must be pushed to all groups in which they are members."

Since the SCIM DB never received these events, we can't properly update it on our end.

[Negin Nafari]

Hi Kenneth, I really appreciate your extra mile here!

You are absolutely looking into the correct case. 

We verified this and thanks for pointing us to this doc from okta. This seems to be the case!

We already have some idea how to fix this from our side

Thank you once again