{
  "openapi": "3.0.0",
  "info": {
    "description": "Welcome to the ConsentHub API documentation. This page documents the REST resources available.",
    "version": "1.0",
    "title": "ConsentHub API Documentation"
  },
  "tags": [
    {
      "name": "Consents",
      "description": "Manages a user's consent."
    }
  ],
  "security": [
    {
      "ApiToken": []
    },
    {
      "OAuth2": [
        "manage:consent-hub-consent"
      ]
    }
  ],
  "paths": {
    "/consent": {
      "post": {
        "tags": [
          "Consents"
        ],
        "summary": "Sets a user's required legal consent statuses",
        "operationId": "updateConsentForUserUsingPOST",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FormsConsentRequest"
              }
            }
          },
          "description": "The update request",
          "required": true
        },
        "responses": {
          "202": {
            "description": "If the validation of request data is successful, the status code will be 202 with no response body. This indicates that the request has been accepted for processing.\nAll update operations are asynchronous and may take several seconds to take effect.\n"
          },
          "400": {
            "description": "The request was invalid"
          },
          "401": {
            "description": "You are not authorized to view the resource"
          },
          "403": {
            "description": "Accessing the resource you were trying to reach is forbidden"
          }
        },
        "deprecated": false
      }
    },
    "/consent-config/get": {
      "post": {
        "tags": [
          "Consents"
        ],
        "summary": "Retrieves user consent and locale information by IP address and user email",
        "operationId": "getConsentConfigUsingPOST",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsentConfigurationRequest"
              }
            }
          },
          "description": "User's email and IP address",
          "required": true
        },
        "responses": {
          "200": {
            "description": "The configuration information was retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentConfiguration"
                }
              }
            }
          },
          "400": {
            "description": "The request was invalid."
          },
          "401": {
            "description": "You are not authorized to view the resource"
          },
          "403": {
            "description": "Accessing the resource you were trying to reach is forbidden"
          }
        },
        "deprecated": false
      }
    }
  },
  "servers": [
    {
      "url": "https://api.atlassian.com/consent-hub"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiToken": {
        "description": "API tokens authenticate a user (Atlassian account) and are used as a replacement for their password over BasicAuth. Go to https://id.atlassian.com/manage/api-tokens to get an API token. <br/> Username is email address. <br/> Password is API token.\n",
        "type": "http",
        "scheme": "basic"
      },
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.atlassian.com/oauth/token",
            "scopes": {
              "manage:consent-hub-consent": "Update and get consent data"
            }
          }
        }
      }
    },
    "schemas": {
      "FormsConsentRequest": {
        "type": "object",
        "required": [
          "email",
          "locale"
        ],
        "properties": {
          "consents": {
            "description": "List of consents to be added or modified.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentRequest"
            }
          },
          "email": {
            "description": "The users email address.",
            "example": "example@email.com",
            "type": "string"
          },
          "formUrl": {
            "description": "URL of the form the user filled out to specify the new consents.",
            "type": "string"
          },
          "locale": {
            "description": "The user's 2-letter country code, or `UNKNOWN`. Used to determine whether the user is in a GDPR locale. Specifying `UNKNOWN` will assume the user is in a GDPR locale. The user locale is most commonly determined based on the user's IP address.\n",
            "type": "string",
            "example": "US"
          },
          "providerId": {
            "description": "Site-specific user ID.",
            "example": "12345",
            "type": "string"
          }
        }
      },
      "ConsentRequest": {
        "type": "object",
        "required": [
          "displayedText",
          "granted",
          "key"
        ],
        "properties": {
          "displayedText": {
            "description": "Legal text displayed to the user on the consent form. Value should be dependent on the consent key.  For example, the displayedText for the `generalMarketingOptIn` consent key is \"Yes, I would like to receive  promotional emails including product news, events, and more from Atlassian and its affiliates.\"\n",
            "example": "Yes, I would like to receive promotional emails including product news, events, and more from Atlassian and its affiliates.\n",
            "type": "string"
          },
          "granted": {
            "description": "Determines whether the consent is granted.",
            "example": true,
            "type": "boolean"
          },
          "key": {
            "type": "string",
            "example": "generalMarketingOptIn",
            "enum": [
              "allowAtlassianShare",
              "allowCcpaSales",
              "allowPartnerShare",
              "generalMarketingOptIn",
              "privacyPolicy",
              "privacyPolicyTrello",
              "termsOfService",
              "termsOfServiceBitbucket",
              "termsOfServiceTrello"
            ]
          }
        }
      },
      "ConsentConfiguration": {
        "type": "object",
        "required": [
          "hasUserMadeChoiceOnMarketingCommunicationOptIn",
          "locale",
          "localeRequiresMarketingCommunicationOptIn",
          "usersChoiceOnMarketingCommunicationOptIn"
        ],
        "properties": {
          "locale": {
            "type": "string",
            "example": "US",
            "description": "2-letter country code determined based on the user IP address. If the IP address is invalid or unable to provide the locale, the locale resolves in UNKNOWN.\n"
          },
          "localeRequiresMarketingCommunicationOptIn": {
            "type": "boolean",
            "description": "Defines if specified locale requires marketing communication opt-in consent.\n"
          },
          "hasUserMadeChoiceOnMarketingCommunicationOptIn": {
            "type": "boolean",
            "description": "Defines if the user made choice on marketing communication opt-in consent. It is always false if the email is not specified.\n"
          },
          "usersChoiceOnMarketingCommunicationOptIn": {
            "type": "boolean",
            "description": "Defines user's choice on marketing communication opt-in consent. It is always false if the email is not specified.\n"
          }
        }
      },
      "ConsentConfigurationRequest": {
        "type": "object",
        "properties": {
          "email": {
            "description": "The user's email address. If provided, this will query ConsentHub for the user's consent preferences using their email address. If not provided, the returned object values will be based solely on the locale determined by the user's IP address. This request field defines `hasUserMadeChoiceOnMarketingCommunicationOptIn` and `usersChoiceOnMarketingCommunicationOptIn` response fields.\n",
            "example": "example@email.com",
            "type": "string"
          },
          "userIp": {
            "description": "The user's IP is used in determining locale via geolocation. This request field defines `locale` and `localeRequiresMarketingCommunicationOptIn` response fields.\n",
            "example": "185.166.140.232",
            "type": "string"
          }
        }
      }
    }
  }
}