Jira Cloud REST API privacy updates and migration guide

Today (01 October 2018) we have published details about the Jira Cloud REST API changes related to user privacy improvements. This also marks the beginning of the deprecation period, ending on 29 March 2019. During this time, API methods will continue to support existing behaviors (i.e., ability to query by username/userkey, receive responses with username/userkey, etc.;); however, at the end of the period, those capabilities will no longer be available.

Jira Cloud REST API migration guide and deprecation notice: https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/

If you have questions or need support, please use this topic and reply.


Are there any plans to change behaviour of /jql/autocompletedata/suggestions ?
Currently it suggests userKey as a value for user fields like assignee.

This functionality is used by the users of our app to construct JQL queries and they like it a lot. If the user key is going to be suggested then the JQL executed by our app won’t work.

Is Jira itself going to autosuggest userKeys in the search?

Hey Neil,

Sorry sent you this in an e-mail too, but just saw the topic here.

Thanks for publishing the deprecation date! Only worry I have is: A ton of the API changes haven’t been actioned yet like stuff linked to https://ecosystem.atlassian.net/browse/ACJIRA-1501

AccountId is currently available to receive, but we can’t start publishing it since most APIs don’t accept it yet. For example I just tried https://codebarrel.atlassian.net/rest/api/3/user/picker?query=<username> with all different types of accountId params or values and none return anything. Only usernames/userkeys work.

So I’m a bit worried since we can’t actually start upgrading any of our stored configs yet to use only accountIds since we can’t use them yet. Further we’ll need some time to convert our configs at runtime, since we can’t write an upgrade task for 1000s for hosts/rules in cloud. Is there a plan about when the APIs will start accepting accountIds for input? And how much time are we going to get before the deprecation date from when that’s available?




Hey Neil,

thanks for sharing the migration guide! I have two questions to your changes:

  • Do you have some kind of best practices how we can call resource in case we are providing select lists in our UI where our users can select other users? Because it seems to me that in certain cases we only get back an account id if a user is very restrictive with its personal data. But the account id is nothing we could show our users in order to select other users, because it’s a technical id and they do not know if this is the correct user they want to choose. Or am I missing something here?
  • Some affected resources provide a header force-account-id in order to use the new account id only. However, instead of setting the option for each resource, is there any other option we can set e.g. in our atlassian-connect.json descriptor to opt-in to those changes in order to test them? I don’t think so, but if it’s the case please let me know :slight_smile:


I would like to emphasize what @andreas wrote. I’m worried that we will end up with a very short time for the implementation and migration of the data.


@jack I agree deprecation should be 6 months AFTER all changes are done. I still have two areas of concern that I have previously asked about but got no reply

  1. What happens to Workflow post functions. As this stage we have no access to the stored post function information, how are we meant to change this.
  2. What happens to users who have an old version of the plugin. Atlassian doesn’t force upgrades (which is fair enough) so how do we handle users with old versions that we can’t change?

It would have been easier if they just stuck the accountId in the username field. This would have drastically reduced the amount of work required in converting existing data, but still wouldn’t have affected my two points above


Hi @andreas. User pickers won’t work with account IDs. That is, you can’t search by a partial match of an account ID. If you need to map an account ID to a user you can call user lookup type APIs.

@daniel2 thanks for your comment. I will look into that. People are looking at some changes to JQL at the moment.

Hi Ben,

Yeah fair enough - so that was maybe not the best example (though I was using the full accountId and not trying to search using partial match). Do all the other APIs already accept accountId as inputs? So for example can I add a watcher to an issue by supplying only the accountId to the API today?

Are you saying that all the work linked from https://ecosystem.atlassian.net/browse/ACJIRA-1501 has been completed already and is now available in Cloud?


To look up a user by exact match you can use /rest/api/2/user?accountId=12345 (or /reset/api/3/user)

There are a number of sub-tickets to the one you mentioned, and I don’t really have visibility of all the details. (As Dave mentions, we are currently working on a solution that will allow change logs to return account IDs.)

The current Jira Cloud API docs should indicate where you can supply account IDs (e.g. /rest/api/3/user)

The ‘User object’ changes say nothing about the field ‘avatarUrls’, but when I look at the examples at the bottom of the linked page of the migration guide I see that avatarUrls will be removed from the API response. Is this based on the user’s privacy settings or will avatarUrls be removed in general?

Sorry Ben,

That doesn’t really answer my question. So we have a deprecation date of 29th of March 2019. That means we have to switch over our API calls to supply accountIds back to Jira’s REST APIs before this date. However we can only do so once you’ve change the APIs to accept accountIds. (e.g. adding a watcher to a Jira issue by accountId, but there’s many more examples).

You’re telling me that you don’t know which APIs support accountId as input and which don’t right now. None of the ACJIRA-1501 issues have had any updates, so I’m assuming no APIs accept accountId as input yet. Is this correct?

Can you give us an estimate as to when and which APIs will accept accountId as input so we can start migration work. And how much time will there be before the 29th of March 2019 deprecation?



Sorry if I was unclear. I’m trying to provide clarity for the Community question, but I’m not involved in the ACJIRA tickets.

It is definitely NOT the case that NO APIs accept accountId as input. The API documentation should indicate where account IDs are accepted. As I indicated yesterday, getting a user lets you request by accountID.

My feeling is that it would be a good idea to raise a support ticket if there are specific APIs that you think should work with account IDs but don’t currently. Adding watchers should accept an account ID. Looking at the documentation for that, it is not very clear what it accepts, but it should work with an account ID.

Echoing what @bkelley said – that if you find any bug, you can post about it here, or submit a bug ticket here.

As for the ACJIRA issues – yep… many of them have not been updated when the changes shipped. Sorry about that. We’ll work with the team to bring those up to date.

1 Like

In the migration guide for Jira Cloud REST APIs the information around user objects mentions that displayName, timeZone etc will be controlled by privacy controls in user accounts.

Has that been implemented yet? If not is there an ETA and where should we look for the new controls?

I can’t see controls for those user details in https://id.atlassian.com or via a Cloud-instance specific URL like https://example.atlassian.net/people/123456:11111a22-bbb3-44c5-dd66-777ee88f99g0/settings/privacy… where should we expect those controls to be found and will there be any privacy control differences between “managed” and “unmanaged” cloud accounts.

Apologies if I’ve not looked hard enough. I’d like to find these controls to make sure our apps degrade functionality well if users restrict access to their personal data.


I wasn’t sure whether to make this a separate topic/post but am I right in understanding that

JQL will not allow username or userKey in queries. Use accountId instead.

means that JQL as a whole will no longer support searching via usernames or userkeys?

If that is the case, then what is the migration path for existing JQL queries that contain usernames and userkeys?


Hi @jbevan,

Existing JQL will be updated to reference accountId instead of username. This migration will happen transparently and not change any semantics of the query.

Are you asking about JQL stored on your side?

Hi @pweinberger, I’d be interested in a response to that question – my app stores user-defined JQL queries and will need a migration strategy for updating to use accountId. Thanks!

Anyone from Atlassian like to tackle these two questions. At this stage I don’t think I’ll need to worry about the SECOND question (maybe) but I definitely have a problem with the second question.

UPDATE: changed the “I don’t think I’ll need to worry about” from first to second.