Does anyone have the magic incantation required to get the user management API to work

[Michael Beale]

The documentation seems to be completely wrong and completely misleading at the same time.  has anyone cracked this and have an actual guide that works?

[Michael Beale · Accepted solution]

Thanks everyone, this all really helped...  just to summarize for those who come after me:

Option 1 - use the User Management for Confluence app. it is really easy to use.

Option 2 - use the Organizations API provided by Atlassian.  The part I got stuck on initially was endpoint to use for my cloud instance.  It's working fine with https://api.atlassian.com/admin/ as the base URL for the apis.  Postman collection available here: Organization Postman Collection 

Thanks again,

Mike

[Ed Letifov _TechTime - New Zealand_ · Accepted solution]

Hello, @Michael Beale 

Save yourself time – start a free 30 day trial of our User Management for Confluence app and you will be able to do exactly what you are trying to do via UI.

You can see the description of the Bulk User Actions feature on our website. You can either deactivate users, or suspend them, or simply remove them from the licensing group associated with Confluence to reclaim back your licenses and save costs.

If you have any questions – reach out to our 24x7 support (yes, even for trials). The chat widget is on the bottom right of the website.

[Trudy Claspill · Accepted solution]

Hello @Michael Beale 

Welcome to the Atlassian community.

What documentation are you referencing? Can you provide a link?

Can you tell us more about what you have tried, specifically, and the results you got?

What API endpoint(s) did you try? What parameters did you provide? What payload did you submit?

(Obscure confidential information like emails and API tokens.)

[Trudy Claspill]

Thank you for that additional information @Michael Beale 

You said "All of which give conflicting guidance on what API endpoint to use."

What task are you trying to execute? There are different levels of user management for accomplishing different tasks, and different API endpoints may apply.

And there are two types of API tokens; personal tokens that non-admin user would create for accessing endpoints available for an application, and an Organization API token that would be used for accessing endpoints at the Organization level.

Let us focus on a specific scenario to ensure we offer you accurate advice.

[Michael Beale]

I'm trying to do the user management - I need to remove a bunch of users (>400) and I'd rather not do them one at a time in the UI since Confluence doesn't believe in bulk operations it seems.

[Trudy Claspill]

What do you mean exactly by "remove users"?

1. Remove their access to the Confluence app?
2. Remove their access to the site?
3. Remove the users from the Organization?

Is your company using an integration with an IdP for provisioning users? Is allocating access to apps part of that provisioning; i.e. by provisioning user groups and granting user groups access to the apps?

[Michael Beale]

we have over 900 licenses we're being charged for.  only a fraction of them are actually being used.  I'm trying to reduce our bill by removing the inactive users.

[Michael Beale]

Is the rest API so complicated that you can only answer specific questions and not just give a "here's how to really use our API's, any of them?"  that seems a bit broken and non-user friendly.

[Trudy Claspill]

Hello @Michael Beale 

Be advised that this is a user community where users can help other users solve problems. I am just another user of the products, not Atlassian technical support.

I'm asking the questions to ensure that I research the correct information and provide you with the correct references. I don't work much with the user management APIs, so I want to double check before providing suggestions to you.

It is therefore helpful to understand the specific scenario you are trying to execute. As I mentioned, there are multiple APIs that serve different purposes. I don't want to end up providing advice to you about removing a user from your Organization when your scenario is about reducing license consumption for a single app.

On a side note, if your Organization is using and IdP and User Provisioning and has claimed Domains, that is another way in which users may be granted access to the app automatically. Removing the individual users' app access now might address your issue temporarily, but the issue may recur if the root cause is not understood. Allowing users to invite other users without requiring Admin approval on the access request is another way in which an organization may lose control of license allocation.

[Trudy Claspill]

Are the user accounts managed or non-managed?

How are the users granted access to your apps? Are they added to a user group and the user group has access (members of the group are given access to the app)? Are they automatically granted access based on their login domain?

You did not say if you already have the list of users, or if you are trying to also derive a list of inactive users.

If you are trying to get information about when a user was last active in an app you would reference this API endpoint:

https://developer.atlassian.com/cloud/admin/organization/rest/api-group-users/#api-v1-orgs-orgid-directory-users-accountid-last-active-dates-get

The information about authentication and the URI to use in the endpoint are on the first page:

https://developer.atlassian.com/cloud/admin/organization/rest/intro/#About

You need your Organization's ID, an organization admin token, and the ID for the user account. Links to getting your Organization's ID and creating a token are in the Authentication section of the above document. 

I was successful in executing the endpoint with a non-scoped Organization admin API token, the organization id for my organization, and a valid user account id within my organization.

curl --request GET \
--url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/directory/users/{userID}/last-active-dates' \
--header 'Authorization: Bearer {token}' \
--header 'Accept: application/json' 

If you want to suspend the user's access to all apps within all sites in your Organization then this endpoint (from the same documentation) can be used:

https://developer.atlassian.com/cloud/admin/organization/rest/api-group-users/#api-v2-orgs-orgid-directories-directoryid-users-accountid-suspend-post

That removes them from your list of billed users while keeping their user account listed in your directory. The user can still log in to Atlassian Cloud, but cannot access your apps. If the same account has access to other apps in other Organization then they could still access those.

If you want to remove them from your User Directory entirely, which also removes their ability to access your apps and removes them from your billed users, use this endpoint:

https://developer.atlassian.com/cloud/admin/organization/rest/api-group-users/#api-v2-orgs-orgid-directories-directoryid-users-accountid-delete

If you want to remove their access to just the Confluence app while leaving their access to other apps, you will likely need to remove them from a user group. 

If they were granted access automatically based on their login domain, then they were likely added to the built-in group for User access to the app. That is typically named something like 'confluence-users-{orgName}'. You can find that name in the Groups tab in the user's account through the admin hub.

To remove a user from a user group you would use this API endpoint (from the same documentation as above):

https://developer.atlassian.com/cloud/admin/organization/rest/api-group-groups/#api-v2-orgs-orgid-directories-directoryid-groups-groupid-memberships-accountid-delete

If the accounts are managed, and if you are using an IdP and user provisioning including user group provisioning, and access is granted to the members of a provisioned user group, then you may not be able to remove the user from that provisioned group through the API. Instead you may need to go to your IdP and change their group membership there, and then resynchronize the IdP to Atlassian Cloud.

The Confluence Cloud API documents you referenced do not provide endpoints that let you manage a user's access to the Confluence app.

In the three documents you mentioned:

• https://developer.atlassian.com/cloud/confluence/rest/v2/intro/#auth
• https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis
• https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-user/#api-users-bulk-post

...I'm not sure what you are referring to when you said they give conflicting guidance on what endpoint to use. They all indicate that you use your site base URL with the documented endpoints. If you would like to explore that, can you provide details about what you saw in the documents that was in conflict?

The endpoints in those documents are for accessing functionality within the Confluence application. Managing users in your Organization and managing users' access to your apps is not within the scope of the Confluence API.

The User Management REST API also does not provide access to manage the users' access to your apps, but it seems like you tried to use one of its endpoints.

That document does specify that a different base needs to be used with the endpoints in the UM API documentation.

https://api.atlassian.com/users/{resource}

I hope I have managed to provide you with useful information. If this has raised more questions or anything I wrote is unclear, please let me know.

[Michael Beale]

so I created scoped API tokens for both Confluence and Teams as well as a classic un-scoped API Token.

Then I tried to follow the following guides: 

• https://developer.atlassian.com/cloud/confluence/rest/v2/intro/#auth
• https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis
• https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-user/#api-users-bulk-post

All of which give conflicting guidance on what API endpoint to use.  I tried using:

• https://api.atlassian.com/ex/confluence/
• https://api.atlassian.com/users/XXXX/manage/profile
• https://intel-ncl.atlassian.com/rest/api/users/XXXXX/manage/profile

I tried using 

--header 'Authorization: Bearer XXXXX' (in curl)

and 

-u michael.beale@intel.com: XXXX' (in curl)

I also downloaded the Postman collections:

• user-management.postman
• confcloud.2.postman
• organization.postman

And even with all of that all I get is 401 errors, and the occasional 403.