Last updated Apr 8, 2024

ConsentHub API

Introduction

ConsentHub is a system for managing user consent and subscriptions, and collecting general marketing opt-in (GMOI) consent when needed. This is a quick How-To guide for using the ConsentHub API. It describes a few common use cases for user management in ConsentHub.

Consent of the data subject means any freely given, specific, informed and unambiguous indication of the data subject's wishes by which he or she, by a statement or by a clear affirmative action, signifies agreement to the processing of personal data relating to him or her.

General Marketing Opt-In (GMOI) consent indicates whether a user opted in to use their personal information for marketing purposes such as marketing emails.

Hosts

ConsentHub can be accessed via https://api.atlassian.com

Authorization

Access to ConsentHub endpoints is granted via client API Token (Basic Authentication).

API Token

API Token value is used as a password for HTTP basic authentication.

To use API Token authorization the client needs to send HTTP requests with the Authorization header that contains the Basic prefix followed by a space and a base64-encoded string email:API Token. For example, to authorize with email@example.com email and 4ojPSCFDbUtTQhjisU0A6A3A API Token value the client would send:

Authorization: Basic ZW1haWxAZXhhbXBsZS5jb206NG9qUFNDRkRiVXRUUWhqaXNVMEE2QTNB

To obtain a client API Token, go to https://id.atlassian.com/manage/api-tokens

See more info here

Please reach out to Scott Grieder or Desmond Ng to be added to the ConsentHub allow list. For Basic authentication, the user needs also to provide their email address.

To review all ConsentHub endpoints see API reference.

Common Use Cases

Client needs to update GMOI consent

APIs for updating GMOI consent in ConsentHub must ensure that the user grants consent for the following legal diclaimer text: "Yes, I would like to receive promotional emails including product news, events, and more from Atlassian and its affiliates."

To see an example request see the API reference

Client needs to get a user locale based on the user's IP address

Request

1
2
POST /consent-hub/consent-config/get HTTP/1.1
Host: api.atlassian.com
Accept: application/json
Content-Type: application/json

{
  "userIp": "102.12.1.2"
}

Response

As the request doesn't include email, hasUserMadeChoiceOnMarketingCommunicationOptIn and usersChoiceOnMarketingCommunicationOptIn will always be false.

1
2
{
  "locale": "GB",
  "localeRequiresMarketingCommunicationOptIn": true,
  "hasUserMadeChoiceOnMarketingCommunicationOptIn": false,
  "usersChoiceOnMarketingCommunicationOptIn": false
}

Client needs to get consent status for a user with a given email

Request

1
2
POST /consent-hub/consent-config/get HTTP/1.1
Host: api.atlassian.com
Accept: application/json
Content-Type: application/json

{
  "email": "example@email.com",
  "userIp": "185.166.140.232"
}

Response

Here, hasUserMadeChoiceOnMarketingCommunicationOptIn and usersChoiceOnMarketingCommunicationOptIn will be determined by the user's consent preferences (if they exist). If a user does not exist for the provided email, this endpoint will act the same as if no email was provided.

1
2
{
  "locale": "GB",
  "localeRequiresMarketingCommunicationOptIn": true,
  "hasUserMadeChoiceOnMarketingCommunicationOptIn": true,
  "usersChoiceOnMarketingCommunicationOptIn": false
}