By 29 April 2019, we will remove personal data from the API that is used to identify users, such as username
and userKey
, and instead use the Atlassian account ID (accountId
). Additionally, we plan to restrict the visibility of other personal data, such as email, in conjunction with a user's profile privacy settings.
This guide shows you how to update your app or integration to adopt the GDPR-related changes for the Confluence Cloud REST APIs. It describes how the user privacy improvements affect the REST APIs, provides a migration path to the new REST APIs, and lists all of the REST API changes.
Atlassian is making a number of changes to our products and APIs to improve user privacy in accordance with the European General Data Protection Regulation (GDPR).
For Confluence Cloud, these changes include:
Changes to how users are identified: Personal data that is used to identify users, such as the username
and userKey
, will be removed from the REST APIs. Users will be identified by their Atlassian account ID instead.
Changes to the visibility of user information: Users will be able to restrict the visibility of their personal data through their user profile privacy settings, or in the case of a managed account, the visibility settings that are decided by the site administrator. This means that fields such as email will only be returned by the API if the user has permitted that data to be visible. Note that this means that some fields can be null.
Changes to Atlassian Connect APIs: All personal data will be removed from Connect REST APIs and replaces with accountId where appropriate.
The REST API changes will be introduced alongside the existing REST API. The existing REST API will be available until the end of the deprecation period. Until this time, you can use either the GDPR-compliant or non-GDPR compliant version of the REST API. An opt-in mechanism will be provided for testing, which will force Confluence Cloud to only use the GDPR-compliant version of the REST API (see Testing GDPR changes section).
Below is a high-level summary of the REST API changes:
Operations that currently accept a username
and/or userKey
will also accept an Atlassian account ID (accountId
). After the deprecation period ends, only an accountId
will be accepted.
Operations that currently return a username
and/or userKey
will also return an Atlassian account ID (accountId
). After the deprecation period ends, only an accountId
will be returned.
Operations that currently use a username
and/or userKey
as a search clause (for example, JQL) will also use an Atlassian account ID. After the deprecation period ends, only an accountId
may be used.
The User object will be changed: Identifying personal data, such as username
and/or userKey
, will be removed and other personal data, such as email, will be displayed according to user settings.
To understand how to update your app or integration, read the list of REST API changes in the next section. You'll find the changes listed by resource and instructions on what you need to update.
1 2curl --request POST \ --url 'https://your-domain.atlassian.net/wiki/rest/api/content/{id}/restriction' \ --user 'email@example.com:' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '[ { "operation": "administer", "restrictions": { "user": [ { "type": "known", "username": "", "userkey": "", "accountId": "", } ], "group": [ { "type": "group", "name": "" } ] } } ]'
The username
and userKey
fields will no longer be accepted. Use accountId
instead.
user
objects will have changes to their fields. See User for the full list of changes.{sourceType}
is user
, {sourceKey}
is currently expected to be userKey
. This will be deprecated. Instead, when {sourceType}
is user
, {sourceKey}
will be expected to be accountId
.{sourceType}
or {targetType}
is user
, the response body will contain a user reference. See User for the full list of changes.Relationdata.createdBy
is a user reference. See User for the full list of changes.POST /rest/api/space?
, the request body can contain references to users in the permissions section. For those users, there will be changes to the fields accepted. See the example below:1 2curl --request POST \ --url 'https://your-domain.atlassian.net/wiki/rest/api/space' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "key": "<string>", "name": "<string>", "description": { "plain": { "value": "<string>", "representation": "<string>" } }, "permissions": [ { "subjects": { "user": { "results": [ { "type": "known", "username": "<string>", "userKey": "<string>", "accountId": "<string>", "profilePicture": { "path": "<string>", "width": 2154, "height": 2154, "isDefault": true }, "displayName": "<string>", "operations": [ { "operation": "administer", "targetType": "page" } ], "details": {}, "personalSpace": { "id": 2154, "key": "<string>", "name": "<string>", "type": "<string>", "status": "<string>", "_expandable": {}, "_links": {} }, "_expandable": { "operations": "<string>", "details": "<string>", "personalSpace": "<string>" }, "_links": {} } ], "size": 2154 }, "group": { "results": [ { "type": "group", "name": "<string>", "_links": {} } ], "size": 2154 }, "_expandable": { "user": "<string>", "group": "<string>" } }, "operation": { "operation": "administer", "targetType": "page" }, "anonymousAccess": true, "unlicensedAccess": true } ] }'
The username
and userKey
fields will no longer be accepted. Use accountId
instead.
user
objects will have changes to their fields. See User for the full list of changes.username
and userKey
are deprecated and will be removed.accountId
parameter must be used to identify a user.Field | Change | Nullable | Notes |
---|---|---|---|
name | REMOVED | N/A | use accountId instead. |
key | REMOVED | N/A | use accountId instead. |
details.personal.email | REMOVED | N/A | This field will be removed. It will be moved to the top level field email |
details.personal.im | REMOVED | N/A | This field will be removed. This data will no longer be available in Confluence. |
details.personal.website | REMOVED | N/A | This field will be removed. This data will no longer be available in Confluence. |
details.personal.phone | REMOVED | N/A | This field will be removed. This data will no longer be available in Confluence. |
details.business.position | REMOVED | N/A | This field will be removed. This data will no longer be available in Confluence. |
details.business.department | REMOVED | N/A | This field will be removed. This data will no longer be available in Confluence. |
details.business.location | REMOVED | N/A | This field will be removed. This data will no longer be available in Confluence. |
accountId | ADDED or CURRENT | No | This field will be added. It is the new primary identifier for users, shared across all Atlassian systems. |
email | ADDED or CURRENT | Yes | new top level field, moved from details.personal.email . Can be null, depending on each user's privacy settings. |
profilePicture | CHANGED | Yes | Can be null, depending on each user's privacy settings. |
displayName | CHANGED | Yes | Can be null, depending on each user's privacy settings. |
accountType | ADDED | No | See Webhooks below. |
username
, key
are deprecated and will be removed.accountId
parameter must be used to identify a user.user
objects will have changes to their fields. See User for the full list of changes.User objects in a webhook payload have a new field: accountType
. This field is used to distinguish normal users from app users.
Valid values:
customer
: A regular Atlassian user account.app
: A system account used for Connect applications and OAuth 2.0 to represent external systems.Confluence provides CQL as a method of forming complex queries to use with the search API. A number of these fields will be changing their behavior or will become deprecated:
Field | Change | Notes |
---|---|---|
user | CHANGED | This field currently accepts username . It will accept accountId instead. |
creator | CHANGED | This field currently accepts username . It will accept accountId instead. |
mention | CHANGED | This field currently accepts username . It will accept accountId instead. |
watcher | CHANGED | This field currently accepts username . It will accept accountId instead. |
contributor | CHANGED | This field currently accepts username . It will accept accountId instead. |
user.userkey | REMOVED | Use user.accountId instead. |
creator.userkey | REMOVED | Use creator.accountId instead. |
contributor.userkey | REMOVED | Use contributor.accountId instead. |
mention.userkey | REMOVED | Use mention.accountId instead. |
watcher.userkey | REMOVED | Use watcher.accountId instead. |
Furthermore, the CQL function currentUser()
will change to return the accountId
instead of username
. This way, queries using the form below will continue to function correctly without any change required:
1 2user=currentUser()
If you want to test your changes, you can force the REST APIs to only use GDPR-compliant functionality by setting the query parameter privacyMode=true
in any REST API call. For example, if you get a user and set privacyMode=true
then the response will not include a username
and userkey
.
You can choose to enable privacyMode
until the end of the deprecation period, if you want to opt in early to the new GDPR-compliant REST APIs. Once the deprecation period is over, GDPR-compliant functionality will be enforced in the REST APIs, regardless of the privacyMode
parameter.
The Confluence XML-RPC, JSON-RPC and SOAP APIs have been deprecated since Confluence 5.5, which was released in 2016. See these related Confluence Server documents for more information:
As part of the changes we are making to our APIs to improve user privacy, these APIs will be removed completely. We will be publishing documentation describing how to migrate from these API endpoints to the REST API in the near future.
Rate this page: