New Organization APIs to power admin automation

[#1]

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 10 APIs are now generally available:

Directory:

1. Get directories
   

   GET /v2/orgs/{orgId}/directories

Group management:

1. Create group
   

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

2. Delete group
   

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

3. Grant access to group
   

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

4. Remove access from group
   

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

5. Add user to group
   

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

6. Remove user from group
   

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

User management:

1. Suspend user access in directory
   

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

2. Restore user access in directory
   

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

3. Remove user from directory
   DEL /v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}

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:

1. Create group
   

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

2. Delete group
   

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

3. Assign roles to a group
   

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

4. Revoke roles from a group
   

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

5. Add user to group
   

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

6. Remove user from group
   

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

User management:

1. Suspend user access
   

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

2. Restore user access
   

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

3. Remove user access
   

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

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

[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: 

1. Identify the ID of your organization. You can typically find this in the URL of your organization: https://admin.atlassian.com/o/<orgID>
2. 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>
3. 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'

4. 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...? ;)