nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

New Organization APIs to power admin automation

Aneita

Hi everyone,

We’re excited to announce the general availability of new public Organization APIs, empowering all organization admins to automate their workflows! These APIs are available to organizations on both the original and centralized user management experiences.

For admins on the original user management experience, having APIs to automate user and group management tasks has been a long-standing request. With this release, you can now simplify your workflows and integrate with internal systems, streamlining your job.

🟢 New v2 Organization APIs

The following 12 APIs are now generally available:

Directory:

Get directories
```
GET /v2/orgs/{orgId}/directories
```

Group management:

Create group

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

Delete group

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

Grant access to group

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

Remove access from group

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

Add user to group

POST /v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/memberships

Remove user from group

DEL /v2/orgs/{orgId}/directories/{directoryId}/groups/{groupId}/memberships/{accountId}

Get groups in an organization

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

User management:

Suspend user access in directory

POST /v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}/suspend

Restore user access in directory

POST /v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}/restore

Remove user from directory

DEL /v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}

Get users in an organization

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

Organizations with the centralized user management experience will only have one directory. Organizations with the original user management experience may have multiple directories, and can use the 'Get directories' API to specify which directory (or userbase) to make updates to.

While similar APIs have existed for centralized user management, this update extends those capabilities to organizations using the original user management experience ensuring everyone can benefit from API-powered automation.

⚠️ Deprecation of v1 Organization APIs

With the general availability of these new APIs, we’ll soon begin deprecating the following equivalent v1 Organization APIs.

Group management:

Create group
```
POST /v1/orgs/{orgId}/directory/groups
```

Delete group

DEL /v1/orgs/{orgId}/directory/groups/{groupId}

Assign roles to a group

POST /v1/orgs/{orgId}/directory/groups/{groupId}/roles/assign

Revoke roles from a group

POST /v1/orgs/{orgId}/directory/groups/{groupId}/roles/revoke

Add user to group

POST /v1/orgs/{orgId}/directory/groups/{groupId}/memberships

Remove user from group

DEL /v1/orgs/{orgId}/directory/groups/{groupId}/memberships/{accountId}

Search for groups within an organization
```
POST /v1/orgs/{orgId}/groups/search
```

User management:

Suspend user access

POST /v1/orgs/{orgId}/directory/users/{accountId}/suspend-access

Restore user access

POST /v1/orgs/{orgId}/directory/users/{accountId}/restore-access

Remove user access

DEL /v1/orgs/{orgId}/directory/users/{accountId}

Search for users in an organization
```
POST /v1/orgs/{orgId}/users/search
```

These v1 APIs will remain available until 30 June 2026. After this date, they will be fully deprecated.

We recommend starting your migration to the new APIs as soon as possible to take advantage of improved functionality and consistency.

We’re excited to see how you use these new APIs to supercharge your admin workflows!

If you have feedback, questions, or want to share how your organization is using these APIs, drop a comment below. We’d love to hear from you!

Aneita

Comments

Sami Shaik

Thank you so much. This is indeed, much useful and helpful for us further.

Alfonso Leiva

Write a comment ... Is there any quick/easy guide to help me understand how can I use these?

It seems with the regular browser authentication I can't use the Org endpoint to know what my directories are.

I would like to use the endpoints for site access revoke and restore, but I need the directory ID.

Thanks a lot in advance.

Aneita

Hey @Alfonso Leiva

To use these APIs, you'll need to first create an API key for your organization. Once you have this API key, you'll be able to use the public Organization APIs.

In order to suspend and restore users, you would need to:

Identify the ID of your organization. You can typically find this in the URL of your organization: https://admin.atlassian.com/o/<orgID>
Identify the ID of the directory that you want to suspend/restore the user in. You can use the 'Get directories' API to find this.
```
curl --request GET \ --url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories' \ --header 'Authorization: Bearer <your_API_key>' \ --header 'Accept: application/json'
```
This will return you a list of all of the directories in the organization. You will need to extract the directoryId for the directory that you're interested in.
```
"data": [ 
    { 
        "directoryId": "12345678-1234-1234-1234-123456789012", 
        "name": "Primary Directory", 
        "icon": "https://icon1.example.com/icon1.png" 
    }

]
```
You can also find this in the URL when viewing any of your sites in Admin: https://admin.atlassian.com/s/<directoryId>/users/<accountId>
Identify the ID of the user that you want to suspend/restore. You can find this in the URL when viewing the user's profile in Admin (see point 2) or use the 'Get users in an organization' API which will return all users in the org. You can use the supported query parameters to restrict your search for users.
```
curl --request GET \
    --url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/users' \
    --header 'Authorization: Bearer <your_API_key>' \
    --header 'Accept: application/json'
```

Call the suspend/revoke API with this information.

curl --request POST \
    --url 'https://api.atlassian.com/admin/v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}/suspend' \
    --header 'Authorization: Bearer <your_API_key>'

Make sure you're replacing all of the bolded items in the code examples with the relevant IDs.

Hope this helps!

Aneita

Jared Schmitt

Hi @Aneita

Will we ever get an API endpoint to simply rename a group? Please...?

Aneita

Hey @Jared Schmitt

There's a few dependencies that we're still working on resolving before group rename can be a fully supported feature. You can follow this ticket where updates are being posted periodically. Those dependencies must be addressed (and group rename be made a generally available feature) before we can provide an API for this. Totally understand why this would be useful to have!

Jared Schmitt

Last update from 2025-05-30. Hope development moves faster than the "periodic" updates do.

Greg M Pflaum

The new APIs that you listed are still marked Experimental. The API doc says "Methods marked as experimental may change without an earlier notice." When will the Experimental tag be removed, so we can safely move to the new APIs?

Untitled 5.png

AP_ij8hk4

It's super annoying that we can't create non-expiring API keys. I understand broadly why you set max expiration for a year, but not at an org / admin level. If customers need to use API keys for administrative programmatic tasks the least I think Atlassian can do is provide an option that doesn't require reminders and regular rotation of these API keys... Personal access tokens, sure. But let orgs & admins decide if and when (if ever) an administrative API key needs to be changed or rotated.

Yash Bhandarkar_hqkmp3

Hello @Aneita ,

Is there a REST API to GET the details of the User Email Address using REST API.

Can you please confirm over this?

Aneita

@Greg M Pflaum - the experimental tag has been removed from the v2 APIs.

@Yash Bhandarkar - do you mean getting the details of a user by their email address? If so, you can use the 'Get users in an organization' API with the searchTerm query parameter which allows you to provide an email address.

@AP thanks for the feedback. Currently, there's no plans to support non-expiring keys. If this is something that'd be valuable to you, I'd encourage you to raise a feature request for us to track interest.

Paul Wang_06vd00

Could you explain the changes to the roleAssignment in the group list? With the new v2 API, I'm no longer able to retrieve the roleId. It also appears that the relationship between resourceId and role has changed from one-to-one in v1 to one-to-many in v2. This represents a significant structural change, correct?

Daphne Zhang

Hey @Paul Wang could you clarify the specific endpoint you're referring to?

In general, you're correct that the relationship between resourceId and role has changed.

In the v2 APIs, we group all the roles for the same resourceId into a single entry. This was an intentional change for performance reasons, and also to help reduce response payload size.

Guillaume THOMAZON

hey @Daphne Zhang I have a quick question.

This article doesn’t mention that the endpoint /v1/orgs/{orgId}/users will be deprecated.
Could you confirm that this endpoint will still be available in July 2026?
thanks

Daphne Zhang

Hi @Guillaume THOMAZON, are you referring to Search for user in an organization?

If so, yes we've deprecated this endpoint: /v1/orgs/{orgId}/users/search

It will no longer work after June 30, 2026.

You can use Get users in an organization instead: /v2/orgs/{orgId}/directories/{directoryId}/users

I see we didn't include these endpoints in this post, that's an oversight. I'll make sure we update this post to reflect that! In case you missed it, we also announced this deprecation in this changelog which contains the correct and complete list of endpoints for you to review.

We announced new, equivalent APIs in this changelog.

Thank you for your question!

Guillaume THOMAZON

Hi @Daphne Zhang just to be sure.
I am talking about this endpoint https://developer.atlassian.com/cloud/admin/organization/rest/api-group-users/#api-v1-orgs-orgid-directory-users-accountid-last-active-dates-get
It's not mentioned as deprecated.
So, could you confirm that this endpoint will still be available in July 2026?

Thanks

Bipin Thite

Hi @Daphne Zhang I see that an endpoint "Get directories in an organization" (`/v2/orgs/{orgId}/directories`) returns 404 not found error for one of our customer accounts. I guess this might be due that customer account is not migrated to new user experience. Is this correct? If yes, then accounts using legacy architecture won't be able to use `v2` endpoints, unless they migrate to new architecture. Will `v1` endpoints continue to work for accounts not migrated to new user experience beyond July 2026? If not, then it would break the functionality of API-based integrations.

Daphne Zhang

@Guillaume THOMAZON That's correct, Users last active dates endpoint won't be deprecated and will still be available after June 30, 2026.

Daphne Zhang

Hi @Bipin Thite, the v2 endpoints are available to all organizations. If you have a customer who has the legacy user management experience, they should be able to use the v2 endpoints. Most v1 endpoints weren't available for customers with the legacy experience.

Get directories in an organization is a new endpoint released with the v2 APIs and doesn't have a v1 equivalent. This endpoint returns directoryIds that you can use in the Get users in an organization endpoint to return a list of users for one or more directoryIds.

404 is not an expected error response for Get directories in an organization. Can you clarify if it's another endpoint running into this error or elaborate on what your use case is? Thank you!

Matthew Martin

Hi @Daphne Zhang - I'm looking for an update on programmatic service account provisioning and token generation. Our CSA mentioned it was delivered, but I can see no announcements or news about it and I would have expected to see it included in the org v2 APIs.

Daphne Zhang

Hi @Matthew Martin, I don't believe we've released service account APIs. For now, you should create and manage service accounts in Atlassian Administration.

Bipin Thite

Hi @Daphne Zhang . The 404 error for the GET Directories API occurred because the site does not exist in the customer's organization. Support confirmed that v2 endpoints are compatible with both legacy and new user management architectures.

Ben Spillane

Hi @Daphne Zhang

Do you have any recommendations regarding the (secure) use of Org Admin API calls inside Atlassian Automations?

My assumption is the direct endpoint invocations in this article via Curl assist with automation of admin operations when coupled with some form of orchestration or middleware?

I'm specifically curious if there's any secure avenues to inject a Bearer API Key (org admin) into native Atlassian automations send web request action?

Thanks in advance.

Italo Qualisoni_apgou5

I see a REST API related to Service Account, it's marked as Experimental but it's missing critical methods to like Create/Revoke API Tokens for Service Accounts

https://developer.atlassian.com/cloud/admin/api-access/rest/api-group-service-account/#api-orgs-orgid-service-accounts-post

I'm trying to build a similar solution as Matthew Martin to enhance the metadata around API Tokens and make it easier to manage.

Matthew Martin

@Italo Qualisoni I have been told by my CSA that the create token APIs are coming this week. I had a similar response to seeing the create SA API without a token API, which is to say, that's not very useful.

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

api

administration

admin

organization-administration