🚀 New organization APIs available today

[#1]

Hi Atlassian Community,

We’re excited to announce some new user and group management APIs available today to improve your organization administration experience.

⚙️ New APIs

Users:

Get the list of users in an organization

GET /v2/orgs/{orgId}/directories/{directoryId}/users

Get stats about types of users in an organization (e.g. number of admins, active users etc)

GET /v2/orgs/{orgId}/directories/{directoryId}/users/stats

Get all roles assigned to a user

GET /v2/orgs/{orgId}/directories/{directoryId}/users/{userId}/role-assignments

Groups:

Get the list of groups in an organization

GET /v2/orgs/{orgId}/directories/{directoryId}/groups

Get stats about the types of groups in an organization (e.g. number of IdP-synced groups)

GET /v2/orgs/{orgId}/directories/{directoryId}/groups/stats

Get information about a specific group (e.g. how many users are in the group, whether it is managed via an IdP)

GET /v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}

Get all roles assigned to a group

GET /v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/role-assignments

These APIs are available to all customers, regardless of whether you have the centralized user management experience or original user management experience, and will eventually replace our existing APIs including:

GET /v1/orgs/{orgId}/users
POST /v1/orgs/{orgId}/users/search
POST /v1/orgs/{orgId}/groups/search

For more information about these APIs, check out our docs.

You’ll notice that directoryId is a required parameter. If you have only 1 directory in your organization (e.g. if you have the centralized user management experience) or want to retrieve information across all of your organization's directories, you can use the special character -.

For those with the original user management experience, and have more than one directory, we’ll be releasing another API shortly to allow you to get the directoryId for directories in your org that you have permission to manage. This will give you the flexibility to get user or group information across your entire organization, or for a specific directory only.

⏭️ What’s next

These APIs are the first step towards new and improved organizations APIs for managing your users and groups. We’ll continue to update you as new APIs become available (including assigning product roles, updating group memberships etc), giving you more power to automate your admin workflows.

💬 Feedback

If you have any feedback about these new APIs, please leave a comment below and I’ll get back to you!

Cheers,

Aneita
Admin Experience Product Manager

[Darryl Lee]

Hi - any chance there will be an endpoint that can return email addresses for users who have not made their addresses "public" in their Profile Settings?

I realize there are reasons (GDPR) for not making this available in the Find users endpoint, but as an Organization Admin I can see the email addresses of all of our external users when I do a CSV "Export users" from Product Administration. (Despite our request, most of our external users have not changed their Profile settings.)

So as an Org Admin (who has invited all of these external users), I already know their addresses, so it doesn't seem like this should put Atlassian in danger of violating GDPR.

I'm simply asking that there be an Org API endpoint that provides the same information as the CSV export. Ideally it could return email and last access information for all users in a group, rather than forcing me make multiple calls, but hey, I'll take a single user lookup if that's all you can give me.

[Josh]

I second @Darryl Lee's request.

[Darryl Lee]

Oh man, @Josh I have a horrible habit of posting on a forum or asking in chat about something and then FINDING what I was looking for immediately afterwards.

Get user email 

Returns a user's email address regardless of the user's profile visibility settings. 

And also (!!!!): Get user email bulk 

Wow. I don't know how I missed this. According to the Internet Archive those endpoints have been around in some form since at least March 2023 (WHAT!!!)

[Josh]

Haha no worries @Darryl Lee ! :-)

[Darryl Lee]

AUGH, spoke too soon. I got this response:

Requestor must be a whitelisted app (not a user).

Because... dur, it says right there:

For Connect apps, this API is only available to apps approved by Atlassian, according to these guidelines. For Forge apps, this API only supports access via asApp() requests.

UGGGGH, I guess it's time to dig out my Developer account. But yikes, I have to create an "app"? 

[Darryl Lee]

Ugh, I'm reading this ancient (2019!) developer thread started by @Alexandra Kassab and it seems so very focused on making sure Customers don't get spammed by app vendors, which is... noble, sure. But it's not related to my use case.

• Guidelines for requesting access to email address 

Here's my use case, and maybe it resonates with other customers:

• We have partner companies whose employees we onboard to our Jira with their external email addresses. They are all members of a group that is used for granting access. (And taking up a license.)
• Sometimes employees of the partner companies will be reassigned to a different project, leave their companies, etc.
• Those accounts then go idle.
• Because we have a limited number of Jira seats, we would like to deactivate idle accounts (no Jira logins in last 90 days).
• But we want to make sure we don't deactivate a newly created account where the user has not had time to login the first time.

So, the public APIs currently available to me (as an Org Admin) can only give me all the Account Ids for the group members, and for each group member:

• Display Name
• Account Id
• Last Login
• Date added to Org (except we're stuck in the old User Management Experience, so I can't use this Search for users in an organization which is probably related to why the workaround for ACCESS-1423 won't work for me either. *Shakes fist* "Curse you vortex!!"

Part of our process is to generate a shared Excel sheet of "candidates" to review for deactivation, and circulate that to our Partner Managers.

Ideally I'd at least be able to automate the generation of the "candidates" sheet, and maybe even send it out to the Partner Managers.

BUT: I cannot automatically generate this list with the API because I am missing the email addresses. (Because a Partner Manager is not going to be able to identify the users simply by Display Name. And oh yes, Company is usually hidden too.)

So right now I'm doing a manual process of Export users for the group in question, then bringing that into Excel to filter based on Last Login and Date Added (and also excluding users that are on an Exceptions list).

[Aneita]

Hey @Darryl Lee, @Josh 

The new get users API does return email addresses of all users in your org. 

In your example of getting the emails of all users in a group, you can specify groupIds in the query param too e.g. 

https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/users?groupIds={groupId}

The last active info isn't available in this API, but we do have that on our radar to provide an API for. 

Does this help with your use cases? 

Cheers,
Aneita

[Darryl Lee]

Ah, thank you @Aneita I completely missed the groupIds bit, so yes, I believe this would get me a lot closer to what I'm looking for!

Unfortunately, I tested with a few of the groups in my directory, one with 1,472 members, and another with only one member, and I got this error message both times:

"status":504,"error":"Gateway Timeout","message":"Response took longer than timeout: PT14S"

Now, according to the nifty stats endpoint, we have a LOT of users:

14095 active, 2576 inactive.

That's double-, if not triple-counting, because we are on Original User Management, and we have separate JSW and JSM sites with Sandboxes on each. :-{

[Yatish Madhav]

Thanks @Aneita and Atlassian. 

I am assuming that since this is posted under the "Enterprise" group, it is only available to Enterprise plans? It is not mentioned in the article but just want to be sure (before I confirm my sadness on this :) )

I was really happy about this, esp the stats but it seems I will not be able to make use of it much, if the above is true!

Thank you

[Nicolas Esteves]

Hi, is there still no endpoint to leave an organization? That’s unfortunate... :(

[Aneita]

@Darryl Lee - the team's looking into the timeout issue for your org. Will keep you posted. Just to double check as well, are you having issues with the /stats endpoint? I didn't quite understand your comment about double/triple counting users. 

@Yatish Madhav - no sadness to be felt! It's available to everyone, so please give it a go and let us know if you have any feedback. We don't have a group in Atlassian Community just for org administration topics which is why this article has been published under the Enterprise group. 

@Nicolas Esteves - do you mean an API to remove a user from an organization? If so, that's on our radar. 

[Darryl Lee]

@Aneita the users/stats endpoint doesn't time out, but if I'm looking at the single Identity Provider I am syncing using Azure AD for Nested Groups (Microsoft Graph), I see in the 4,872 users.

That's a far cry from the 14095 that the API gives me.

When I say double/triple counting it's because according to support, in Original User Management, each separate product instance has its own unique (but duplicate) set of users. This is what is preventing me from migrating to Centralized User Management.

A few of us discuss this here: https://community.atlassian.com/forums/Enterprise-articles/Cloud-admins-we-re-saving-you-time-on-user-management/bc-p/2944842#M1057

And here: https://community.atlassian.com/forums/Articles/User-management-for-cloud-admins-just-got-easier/bc-p/2956026#M608

To summarize:

darryllee@MYCOMPANY.com is "counted" once (as a separate user) for my Jira site, a second time for my Sandbox Jira site, and a third time for my JSM site (which has fewer agents), a fourth time for my JSM sandbox site, and oh yes, 5th and 6th times for our Confluence and Confluence Sandbox sites.

SO, my theory is that your users/stats endpoint is simply a sum of all of those distinct users. Or at least *maybe* a sum for Jira/Confluence, which are on the same endpoint and share a directory?

[David Bakkers]

...aaannnd over on the Developer Community, the first report of some of the new Org API endpoints having bugs.

Some endpoints return objects that use snake case, not camel case.

[Yatish Madhav]

Thanks @Aneita  - that is good news. Slightly confusing/misleading that it is under Enterprise though

The not-so-good news is that all of those endpoints gives me 404 Oops, you've found a dead link. Still sad ...

I tried that by going to https://yyyyy.atlassian.net/v2/orgs/xxxxx/directories/-/users/stats or https://yyyyy.atlassian.net/v2/orgs/xxxxx/directories/-/users or https://yyyyy.atlassian.net/v2/orgs/xxxxx/directories/-/groups/stats or https://yyyyy.atlassian.net/v2/orgs/xxxxx/directories/-/groups or the individual user or group - using - as we only have 1 directory (where we replaced xxxxx with out Org ID from admin.atlassian.com and yyyyy is our instance subdomain)

I tried the above in the browser directly and using Curl with an API token and it also results in 404 Oops, you've found a dead link

I hope I am not missing something or this is just not available to me? Anyone else?

Thank you

[Nicolas Esteves]

Hi @Aneita,

Thanks for your response! That’s close to what I mean, but more specifically, I’d like the option to leave an organization without having to request it from an org admin. Could you add an endpoint (or a UI feature) that allows users to leave an organization independently?

Thanks!

[Jeffrey Agdol]

Hello everyone,

I'm new here and I just wanted to ask which endpoint is capable of returning user group memberships in our organization?
Just like this for MS Graph
https://graph.microsoft.com/beta/users/user@domain.com/transitiveMemberOf

Thanks in advance.

[Darryl Lee]

Hey @Jeffrey Agdol - I've had to settle for using the Jira endpoint for getting group memberships:

• Get users from group 

Because I'm NOT on the Centralized User Experience, what happens for us is that all of the groups from my Identity Provider (so these are "Organization Directory Groups", I think) get "copied" to both of my Jira/JSM sites group directories.

I can get the group memberships for one of these sites and in my experience it has matched what we see in our IdP (Entra fka Azure AD).

My understanding is that in the Centralized User Experience, there is only ONE directory. I've not gotten to see this since we are unable to be migrated to it.

I've not seen a way to do this in the Admin UI for Organization Directory (Managed accounts), so there's no way for me to sniff around for an unofficial API.

[Kenneth De Coster]

Hello everyone,

If you have issues with running the endpoint, it may be because of an incorrect Directory ID (which is not the SCIM directory ID - but rather the userbase directory). I've written this post to help out with retrieving the Directory ID: https://community.atlassian.com/forums/Atlassian-Platform-articles/Guide-Find-the-directory-ID-for-your-userbase/ba-p/2978766#M153

[Craig Castle-Mead]

Hi @Aneita 

With the promise of a new version of the API, I was hoping that it'd help resolve some of the major issues we are having with Guard, however it falls well short for us. Yes, we have a significant Guard footprint, but we're an enterprise, being charged significant annual licensing costs for this (as it's required to enforce SAML/MFA), and being marketed to that Guard helps enterprises manage their Atlassian Cloud footprint.

• Org overview:
  • Claimed domains - 2300+
  • Directories - 1
  • Accounts (according to the UI)
    • Total - 132901
    • Deactivated - 119731
    • Active (calculated off the above) - 13170
  • Org type - legacy (non-vortex)
  • Distinct Directories (according to /v2/orgs/$orgid/workspaces - 8
• /v2/org/$orgid/users/-/stats
  • Initially got a gateway time out, now getting a response at least (response time  ~ 2 seconds)
  • Roles - 17
  • Active accounts - 12,234
  • Inactive Accounts - 30,943
  • Total accounts - 43,177
  • Why the discrepancy between what the UI is telling us Vs what the API is telling us?
    • While we have 8 directories, and we're on legacy/non-vortex, the org user count is apparently global products * global users. This logic is somewhat backed up by the fact that regardless of the directoryId I hit for /stats, I get the same number of roles/users/accounts back - the ratio of org/directory values is not 8.
      • Active Org Users (13170) / Active Directory Stats Users (12234) - ratio is 1.07
      • Inactive Org Users (119731) / Inactive Directory Stats Users (30943) - ratio is 3.8
    • It's impossible to get an accurate picture of what our Guard footprint actually looks like, as every piece of data we look at responds with different information, so even if one is accurate, we don't know which one it us.
  • I'm assuming there's some form of caching happening here too - which is understandable, but can the logic please be explained so teams are aware of how live the data is they're dealing with? I just de-activated a user, and the /stats results have not changed. Tried again after 1 minute, no change, 5 minutes, the response took 16 seconds - but still no change to the user counts. 15 minutes later, still no change, even if I directoryids that I've not used before.
• /v2/org/$orgid/-/users
  • Default page size is 20, this can be adjusted up to 100. With a 100 limit page, I'm getting an average response time of ~ 6 seconds per page.
  • One of the key use cases on our side for this end point is to sync/cache the Atlassian Guard user database to our environment at least daily, this information is used to support internal recharging, cleanup (ensure accounts are enforced by SAML), marry up the account data Guard has with the additional user metadata we have (office, company, etc) for reporting. So daily, we need to sync all users from the org.
    • With ~ 42,000 total users, and a maximum page size of 100 users, this means there's a need to iterate through 420 pages. At ~ 6 seconds/page, that's ~ 10 pages/minute, that's ~ 45 minutes.
    • The rate limit is at least 60 requests/minute, so we're not going to have to implement monitoring/timing controls to avoid hitting the rate limit assuming no other APIs are being used simultaneously.

I'll provide our Atlassian SEM a link to this post so they can do assist with any internal discussions required.

CCM