Last updatedMay 25, 2018

Major changes to Confluence 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.

Introduction of Atlassian account ID

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

  • The /user/current resource returns a representation of the current user
  • The /group/{groupName}/member resource returns representations of each user in a group
  • The /content resource can expand user-based properties like the creator of the page, version or child comments

For a full list of affected APIs, see the table at the bottom of this post.

In all cases where Confluence 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 Confluence user objects

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

AttributeStatus
selfChanged to reference Atlassian account API URL.
usernameChanged to return a system generated value for new users without notice and then removed following the deprecation period.
userKeyRemoved following the deprecation period.
accountIdWill always be returned. Primary identifier for users.
emailWill be returned if allowed by user's privacy settings. May be null.
displayNameValue returned is driven by user's privacy settings, will be non-null.
profilePictureCurrent attribute will be removed following the deprecation period. New avatar resources will be introduced.

Atlassian will provide a public Atlassian account API to access individual user details later this year. Please watch CONFCLOUD-59871 to be notified about the changes.

Removal of username values from various Confluence API resources

Currently, Confluence users also have a username identifier, which is a mutable, per-user identifier within a single Confluence instance. As we expect API consumers to use accountId as the primary identifier for users, the username and userKey values will be removed from all locations in the future, including as references for mentioning users in storage format, such as <ri:user ri:username="myusername"/>. This will be replaced with <ri:user ri:accountId="abc123"/>. Please watch CONFCLOUD-59872 to be notified about these changes.

Updates to CQL fields that accept username, userkey or email as input

A number of fields in CQL accept username, userKey or email as input. For instance creator.username, user.email or contributor.userKey. Fields that accept username or userKey will be removed, and will instead accept accountId. Fields that accept email as part of the CQL query will only match a user where the email address is visible for that users privacy settings. Please watch CONFCLOUD-59873 to be notified about these changes.

Updates to Confluence APIs which accept user user name or key as input

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

The tables below contain affected API resources and tickets to watch.

Confluence REST APIs changing in response to GDPR

Template

The user representation returned by these resources is changing as described above.

ResourceMethodsTicket to watch for updates
/rest/api/templatePOST, PUTCONFCLOUD-59875
/rest/api/template/blueprint?GETCONFCLOUD-59875
/rest/api/template/page?GETCONFCLOUD-59875
/rest/api/template/:contentTemplateIdGETCONFCLOUD-59875

User

The username and userkey query params are no longer supported. Use the existing accountId query parameter as the replacement. The user representation returned by these resources is changing as described above.

ResourceMethodsTicket to watch for updates
/rest/api/user?GETCONFCLOUD-59874
/rest/api/user/anonymous?GETCONFCLOUD-59874
/rest/api/user/current?GETCONFCLOUD-59874
/rest/api/user/memberof?GETCONFCLOUD-59874
/rest/api/user/watch/content/:contentId?GET, POST, DELETECONFCLOUD-59874
/rest/api/user/watch/label/:labelName?GET, POST, DELETECONFCLOUD-59874
/rest/api/user/watch/space/:spaceKey?GET, POST, DELETECONFCLOUD-59874

Content

The user representation returned by these resources is changing as described above, including fields in the version, history and restrictions expansions. Rendered macro output will only include user information that the requesting user is allowed to see.

ResourceMethodsTicket to watch for updates
/rest/api/content?GET, POSTCONFCLOUD-59876
/rest/api/content/blueprint/instance/:draftId?POST, PUTCONFCLOUD-59876
/rest/api/content/:id?GET, PUTCONFCLOUD-59876
/rest/api/content/:id/child?GETCONFCLOUD-59876
/rest/api/content/:id/child/attachment?GET, POST, PUTCONFCLOUD-59876
/rest/api/content/:id/child/comment?GETCONFCLOUD-59876
/rest/api/content/:id/child/:type?GETCONFCLOUD-59876
/rest/api/content/:id/descendant?GETCONFCLOUD-59876
/rest/api/content/:id/descendant/:type?GETCONFCLOUD-59876
/rest/api/content/:id/history?GETCONFCLOUD-59876
/rest/api/content/:id/history/:version/macro/id/:macroIdGETCONFCLOUD-59876
/rest/api/content/:id/notification/child-created?GETCONFCLOUD-59876
/rest/api/content/:id/notification/created?GETCONFCLOUD-59876
/rest/api/content/:id/restriction?GET, POST, PUTCONFCLOUD-59876
/rest/api/content/:id/restriction/byOperation?GETCONFCLOUD-59876
/rest/api/content/:id/restriction/byOperation/
:operationKey?
GETCONFCLOUD-59876
/rest/api/content/:id/restriction/byOperation/
:operationKey/user?
GET, POST, PUTCONFCLOUD-59876
/rest/api/content/:id/version?GETCONFCLOUD-59876
/rest/api/content/:id/version/:versionNumber?GETCONFCLOUD-59876
/rest/api/contentbody/convert/:to?GETCONFCLOUD-59876

The format of the CQL query param is changing when querying user fields, as well as the embedded user representations in content and spaces.

ResourceMethodsTicket to watch for updates
/rest/api/content/search?cql={{cql}}GETCONFCLOUD-59876
/rest/api/search?cql={{cql}}GETCONFCLOUD-59877

Groups

The user representation returned by this resource is changing as described above.

ResourceMethodsTicket to watch for updates
/rest/api/group/:groupName/member?GETCONFCLOUD-59878

Relations

The user representation returned by these resources is changing as described above.

ResourceMethodsTicket to watch for updates
/rest/api/relation/:relationName/from/
:sourceType/:sourceKey/to/:targetType?
GETCONFCLOUD-59879
/rest/api/relation/:relationName/from/
:sourceType/:sourceKey/to/:targetType/:targetKey?
GET, PUT, DELETECONFCLOUD-59879
/rest/api/relation/:relationName/to/
:targetType/:targetKey/from/:sourceType?
GETCONFCLOUD-59879

Spaces

The user representation returned by these resources is changing as described above, including fields in the history and permissions expansions.

ResourceMethodsTicket to watch for updates
/rest/api/space?GET, POSTCONFCLOUD-59880
/rest/api/space/_privatePOSTCONFCLOUD-59880
/rest/api/space/:spaceKey?GET, PUTCONFCLOUD-59880
/rest/api/space/:spaceKey/content?GETCONFCLOUD-59880
/rest/api/space/:spaceKey/content/:type?GETCONFCLOUD-59880

Other APIs changing in response to GDPR

APIResourcesTicket to watch for updates
WebhookscreatorKey, creatorName, modifierKey, modifierName, user, userKeyCONFCLOUD-59881
Will be removed and replaced with accountId equivalents.
Context parametersuser_idCONFCLOUD-59882
Already deprecated and will be removed.
Context parametersuser_keyCONFCLOUD-59882
Already deprecated and will be removed.
User context JWT claimSee related notice.