Last updatedMay 24, 2018

Major changes to Jira Cloud REST APIs are coming to improve user privacy

Throughout 2018 and 2019, Atlassian will undertake a number of changes to our products and APIs in order to improve user privacy in accordance with the European General Data Protection Regulation (GDPR). In addition to pursuing relevant certifications and data handling standards, we will be rolling out changes to Atlassian Cloud product APIs to consolidate how personal data about Atlassian product users is accessed by API consumers.

This post will summarize the relevant API changes that we expect to make in the future. Where possible, we will link to specific Jira issues that you can track to stay up-to-date about specific changes and when they will go into effect. We encourage you to watch these issues and check this page regularly in order to stay up to date about any API changes.

This announcement provides supplementary information to related Major changes to Atlassian Connect APIs are coming to improve user privacy.

Introduction of Atlassian account ID

User objects are returned by a number of Jira REST API endpoints. For example:

  • The /user endpoint returns representations of Jira users
  • The /groups endpoint can be expanded to return representations of each user in a group
  • The /issue endpoint returns users in user-based fields like assignee, reporter, comments, and worklogs
  • The /component resource returns user details of the component lead

For a full list of affected APIs, see the table at the bottom of this post. In all cases where Jira APIs return user details, the Atlassian account ID (accountId) field is now included in the object body. Atlassian account IDs are a unique identifier for every Atlassian account user and should be considered the primary key for interacting with users via Atlassian APIs.

If you do store user data, we strongly encourage you to use Atlassian account IDs as the identifier for your data.

Changes to Jira user objects

When a user object is returned in a Jira API today, it includes a number of attributes about a user, like emailAddress, displayName, and avatarUrls. These user objects will change substantially following the deprecation period. Below is a summary of changes:

selfChanged to reference Atlassian account API URL.
nameRemoved following the deprecation period.
keyWill be changed to return the same value as accountId for new users without notice and then removed
following the deprecation period.
accountIdWill always be returned. Primary identifier for users.
emailAddressWill be returned if allowed by user's privacy settings. May be null.
displayNameValue returned is determined by user's privacy settings. Will be non-null.
activeNo change
timeZoneWill be returned if allowed by user's privacy settings. May be null.
avatarUrlsCurrent avatar URL will be removed following the deprecation period. New avatar resources will be introduced.
nickname(New) A user-customizable "handle" to refer to a user, such as in an @mention

Atlassian will provide a public Atlassian account API to access individual user details later this year. Please follow the following ticket to be notified: ACJIRA-1510

Removal of user name values from various Jira API resources

Currently, Jira users also have a user name identifier, which is a mutable per-user identifier within a single Jira instance. As we expect API consumers to use accountId as the primary identifier for users, the user name value will be removed from all locations in the future, including as markup for mentioning users in a text field, such as [~username]. This will be replaced with [~accountId]. Please follow ACJIRA-1511 to be notified when this change is introduced.

Updates to APIs which accept user name or key as input

A number of Jira API endpoints currently accept Jira user names as path parameters, query parameters, or in request bodies. Jira will introduce new versions for each affected API that accepts the username or userKey parameters. In all cases, requests that previously used a user name or user key will only accept an accountId in the new API version.

The table below contains affected API endpoints and tickets to follow:

EndpointMethodsTicket to follow for updates
/api/2/userGET, POST, DELETEACJIRA-1497
/api/2/user/passwordPUTAlready removed as of November 2016
/api/2/user/avatarGET, POST, PUT, DELETEAlready deprecated.
/api/2/user/avatar/temporaryGET, POST, PUTAlready deprecated.
/api/2/user/columnsGET, POST, DELETEACJIRA-1497
/api/2/user/propertiesGET, PUTACJIRA-1497
/api/2/user/properties/{propertyKey}GET, DELETEACJIRA-1497
/api/2/componentPOST, PUTACJIRA-1498
/api/2/group/userGET, DELETEACJIRA-1500
/api/2/issue/{issueIdOrKey}PUT, POSTACJIRA-1501
/api/2/issue/{issueIdOrKey}/watchersPOST, DELETEACJIRA-1501
/api/2/viewuser/application/{applicationKey}POST, DELETEAlready removed as of November 2016
/rest/servicedeskapi/organization/{organizationId}/userPOST, DELETEACJIRA-1507
/rest/servicedeskapi/request/{issueIdOrKey}/participantPOST, DELETEACJIRA-1507
/rest/servicedeskapi/servicedesk/{serviceDeskId}/customerPOST, DELETEACJIRA-1507
WebhooksSee ACJIRA-1508
Context parametersuser_idAlready deprecated and will be removed.
user_keyAlready deprecated and will be removed.
profileUser.nameSee ACJIRA-1509
profileUser.keySee ACJIRA-1509