Last updatedAug 9, 2019

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 page summarizes the relevant API changes that we expect to make in the future. Where possible, we provide a 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 object body now includes the user's Atlassian account ID (accountId). The accountId is a unique identifier for an Atlassian account user and should be considered the primary key for interacting with users via Atlassian APIs.

If you store user data, we strongly encourage you to use accountId to identify users.

Changes to Jira user objects

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

AttributeStatus
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 watch ACJIRA-1510 to be notified about these changes.

Removal of username values from various Jira API resources

Currently, Jira users also have a username 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 watch ACJIRA-1511 to be notified about these changes.

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.

Jira REST APIs changing in response to GDPR

The table below contains affected API resources and tickets to watch.

ResourceMethodsTicket to watch for updates
/api/2/userGET, POST, DELETEACJIRA-1497
/api/2/user/searchGETACJIRA-1497
/api/2/user/assignable/searchGETACJIRA-1497
/api/2/user/passwordPUTAlready removed as of November 2016
/api/2/user/viewissue/searchGETACJIRA-1497
/api/2/user/permission/searchGETACJIRA-1497
/api/2/user/assignable/multiProjectSearchGETACJIRA-1497
/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/myselfGETACJIRA-1499
/api/2/groups/pickerGETACJIRA-1500
/api/2/group/userGET, DELETEACJIRA-1500
/api/2/issue/{issueIdOrKey}PUT, POSTACJIRA-1501
/api/2/issue/{issueIdOrKey}/watchersPOST, DELETEACJIRA-1501
/api/2/project/{projectIdOrKey}/role/{id}PUTACJIRA-1502
/api/2/viewuser/application/{applicationKey}POST, DELETEAlready removed as of November 2016
/api/2/project{projectKey}/avatar/{avatarId}POSTACJIRA-1502
/api/2/dashboardGETACJIRA-1503
/api/2/filterPOSTACJIRA-1504
/api/2/project{projectKey}/avatar/{avatarId}PUTACJIRA-1502
/api/2/users/pickerGETACJIRA-1505
/rest/agile/1.0/board/{boardId}/issueGETACJIRA-1506
/rest/agile/1.0/board/{boardId}/backlogGETACJIRA-1506
/rest/agile/1.0/epic/{epicIdOrKey}/issueGETACJIRA-1506
/rest/agile/1.0/board/{boardId}/epic/none/issueGETACJIRA-1506
/rest/agile/1.0/board/{boardId}/sprint/{sprintId}/issueGETACJIRA-1506
/rest/agile/1.0/issue/{issueIdOrKey}GETACJIRA-1506
/rest/agile/1.0/sprint/{sprintId}/issueGETACJIRA-1506
/rest/servicedeskapi/organization/{organizationId}/
user
POST, DELETEACJIRA-1507
/rest/servicedeskapi/request/{issueIdOrKey}/
participant
POST, DELETEACJIRA-1507
/rest/servicedeskapi/servicedesk/{serviceDeskId}/
customer
POST, DELETEACJIRA-1507
/rest/servicedeskapi/requestPOSTACJIRA-1507
WebhooksACJIRA-1508
Context parametersuser_idACJIRA-1509
Already deprecated and will be removed
user_keyACJIRA-1509
Already deprecated and will be removed
profileUser.nameACJIRA-1509
profileUser.keyACJIRA-1509