Verizon Media Privacy Dashboard Public API Documentation

version v1.6

https://api.processor.oath.com:443/

Introduction

This document describes the API contract for 3rd party data processors to receive notification(s) of a request in relation to the rights under Articles 16, 20, and 21 of the GPDR. The primary goal of the API is to transmit requests that have been received from data subjects to ensure compliance with the EU General Data Protection Regulation will be referred to as "GDPR" henceforth.

Accepting and Processing requests

Data flow narrative

After a user has submitted a GDPR request to the Privacy Dashboard, an HTMLElement, in accordance with the Implementation section that has an uri conforming to the URI Template which resides on the 3rd party processor's domain, will be inserted into the active document. The application that resides at the destination uri may/must validate the following conditions to accept the request:

• MAY validate the referrer matches the regular expression ^https://*.mydashboard.oath.com,
• MUST ensure that the token from the dataSubjectRequest is a valid JSON Web Token, RFC7519, Section 7.2. Use the {baseUri}/publicKey/{keyid} API where the key id is at #/cnf/kid property of the token refer to JSON Web token reference.
• MUST determine the natural language from the browser, if the optional lang attribute is not present on the query string.

Once the request has been validated, the observered data subject MUST be determined from the current session. Upon discovering the data subject, an appropriate action based on the request type which resides in the #/dsr/type Claim of the token from dataSubjectRequest query parameter MUST be taken. The different types of requests are:

• ACCESS - Processors must supply the following information for this type of request:
  • All data pertaining to the data subject in a commonly used and machine readable format.
  • A dictionary describing the data that is: human readable, easily understood, and written in the natural language of the data subject.
• ERASURE - Processors must delete all of the data pertaining to the data subject, and submit a notification upon completion.
• OBJECT - Processors must prevent any further processing of any data pertaining to the data subject, and submit a notification upon acceptance.
• RESTRICT - Processors must prevent any further processing of any data pertaining to the data subject, and submit a notification upon acceptance.

To supply data or submit a notification, the 3rd party processor MUST send the appropriate payload to the endpoint found inside the JWT found in the dataSubjectRequest query param. The target can be found in the #/dsr/target property of the token. See below for details on the JWT token. Reference V1 for the appropriate payloads.

URI Template

Template: {base-uri}?dataSubjectRequest={dataSubjectRequest}&lang={lang}

Example:

https://www.3rdpartytracker.com?dataSubjectRequest=eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpYXQiOiIxNTEyNjkwMjM5IiwiZXhwIjoiMTUxMjk0OTQzOSIsImlzcyI6IkNOPWdkcHIuYXdzLmNvcmUtdHJ1bmssT1U9QXRoZW56LE89T2F0aCxDPVVTIiwiYXVkIjoid3d3LjNyZHBhcnR5dHJhY2tlci5jb20iImNuZiI6eyJraWQiOiIwMDo5ODpCMzpBMjoxQzo2NTpGMDo2OTpDMDo2QjpDMDpDQjpBQzoyNDpCRTpEMjo4MCJ9LCJkc3IiOnsidHlwZSI6IkVSQVNVUkUiLCJ2ZXJzaW9uIjoxLCJ0YXJnZXQiOiJodHRwczovL2NvcmUuZ2Rwci5vYXRoLmNvbTo0NDMvdjEvZGF0YVN1YmplY3RSZXF1ZXN0L0I2QUMwOTk3LTZBQkYtNDAyRC05MDg3LUM2M0VEOUIzMTMxNy9hY2tub3dsZWRnZSJ9fQo=.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&lang=en-US

Parameters:

• base-uri: An uri with the https:// scheme for the registered 3rd party processor.
• dataSubjectRequest: A JSON Web token that conforms to the reference below.
• lang: A optional string that represents the users natural language with the syntax from RFC 3066, Section 2.1

NOTE: All connections must be HTTPS.

JSON Web token reference

Verification:

Must be validated using the {baseUri}/publicKey/{keyid} API where the key id is at #/cnf/kid property from the token prior to accepting the request.

Guaranteed Claims:

• iat: A timestamp from the GMT timezone representing when this token was issued in EPOCH format. Refer to RFC7519, Section 4.1.6
• exp: A timestamp from the GMT timezone representing when this token will expire in EPOCH format. Refer to RFC7519, Section 4.1.4
• iss: Issuer of this token which matches the subject of the public key identified in the confirmation claim. Refer to RFC7519, Section 4.1.1
• aud: audience / processor's requested website of integration. Refer to RFC7519, Section 4.1.2
• jti: A unique identifier for the JWT. Refer to RFC7519, Section 4.1.7
• cnf: the confirmation data for this token. Refer to RFC7800, Section 3.1
  • kid: a Key ID which can be used with the public key API to retrieve the public key to validate this token. Refer to RFC7800, Section 3.4
• dsr: Details for the dataSubjectRequest for which this token was issued.
  • type: a required property that describes the type of the original request. The list below contains the possible values.
    • ACCESS
    • ERASURE
    • OBJECT
    • RESTRICT
  • version: An integer that describes the version of the API being used for publishing.
  • target: The location to send the compiled data and/or submit acknowledgement of receipt.

Optional Claims:

• ident: A list of members that are associated with the identity of the subject

  Example representation:

  {
    "primaryId" : "4EF69B5A-01A7-499A-B3F8-680B7599E682",
    "alias1" : "B98EF0C8-ED81-4F1F-9B9D-76531F0AC5C6"
  }
  

Example ACCESS token guaranteed claim set:

{
    "iat" : "1512690239",
    "exp" : "1512949439",
    "iss" : "CN=gdpr.aws.core-trunk,OU=Athenz,O=Oath,C=US",
    "aud" : "www.3rdpartytracker.com",
    "jti" : "30A2812C-FAA7-49D0-90C6-B4707CD983AF",
    "cnf" : {
        "kid" : "00:98:B3:A2:1C:65:F0:69:C0:6B:C0:CB:AC:24:BE:D2:80"
    },
    "dsr" : {
      "type": "ACCESS",
      "version" : 1,
      "target" : "https://core.gdpr.oath.com:443/v1/dataSubjectRequest/B6AC0997-6ABF-402D-9087-C63ED9B31317/material"
    }
}

Example ERASURE token guaranteed claim set:

{
    "iat" : "1512690239",
    "exp" : "1512949439",
    "iss" : "CN=gdpr.aws.core-trunk,OU=Athenz,O=Oath,C=US",
    "aud" : "www.3rdpartytracker.com",
    "jti" : "30A2812C-FAA7-49D0-90C6-B4707CD983AF",
    "cnf" : {
        "kid" : "00:98:B3:A2:1C:65:F0:69:C0:6B:C0:CB:AC:24:BE:D2:80"
    },
    "dsr" : {
      "type": "ERASURE",
      "version" : 1,
      "target" : "https://core.gdpr.oath.com:443/v1/dataSubjectRequest/B6AC0997-6ABF-402D-9087-C63ED9B31317/acknowledge"
    }
}

Example OBJECT token guaranteed claim set:

{
    "iat" : "1512690239",
    "exp" : "1512949439",
    "iss" : "CN=gdpr.aws.core-trunk,OU=Athenz,O=Oath,C=US",
    "aud" : "www.3rdpartytracker.com",
    "jti" : "30A2812C-FAA7-49D0-90C6-B4707CD983AF",
    "cnf" : {
        "kid" : "00:98:B3:A2:1C:65:F0:69:C0:6B:C0:CB:AC:24:BE:D2:80"
    },
    "dsr" : {
      "type": "OBJECT",
      "version" : 1,
      "target" : "https://core.gdpr.oath.com:443/v1/dataSubjectRequest/B6AC0997-6ABF-402D-9087-C63ED9B31317/acknowledge"
    }
}

Example RESTRICT token guaranteed claim set:

{
    "iat" : "1512690239",
    "exp" : "1512949439",
    "iss" : "CN=gdpr.aws.core-trunk,OU=Athenz,O=Oath,C=US",
    "aud" : "www.3rdpartytracker.com",
    "jti" : "30A2812C-FAA7-49D0-90C6-B4707CD983AF",
    "cnf" : {
        "kid" : "00:98:B3:A2:1C:65:F0:69:C0:6B:C0:CB:AC:24:BE:D2:80"
    },
    "dsr" : {
      "type": "RESTRICT",
      "version" : 1,
      "target" : "https://core.gdpr.oath.com:443/v1/dataSubjectRequest/B6AC0997-6ABF-402D-9087-C63ED9B31317/acknowledge"
    }
}

Implementations

Image tag

Description:

This the default implementation is for those processor(s) which use browser cookies to: identify a data subject, and/or store data pertaining to a data subject. A 1 x 1 pixel image will be placed on the browser's DOM to facilitate communication with the 3rd party processor.

Example HTMLElement added to DOM:

<img src="https://www.3rdpartytracker.com?dataSubjectRequest=eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpYXQiOiIxNTEyNjkwMjM5IiwiZXhwIjoiMTUxMjk0OTQzOSIsImlzcyI6IkNOPWdkcHIuYXdzLmNvcmUtdHJ1bmssT1U9QXRoZW56LE89T2F0aCxDPVVTIiwiYXVkIjoid3d3LjNyZHBhcnR5dHJhY2tlci5jb20iImNuZiI6eyJraWQiOiIwMDo5ODpCMzpBMjoxQzo2NTpGMDo2OTpDMDo2QjpDMDpDQjpBQzoyNDpCRTpEMjo4MCJ9LCJkc3IiOnsidHlwZSI6IkVSQVNVUkUiLCJ2ZXJzaW9uIjoxLCJ0YXJnZXQiOiJodHRwczovL2NvcmUuZ2Rwci5vYXRoLmNvbTo0NDMvdjEvZGF0YVN1YmplY3RSZXF1ZXN0L0I2QUMwOTk3LTZBQkYtNDAyRC05MDg3LUM2M0VEOUIzMTMxNy9hY2tub3dsZWRnZSJ9fQo=.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&lang=en-US" />

IFrame

Description:

This implementation is exclusively for those processor(s) which use browser local storage to identify a data subject, and/or store data pertaining to a data subject. A iframe element will be placed on the browser's DOM to facilitate communication with the 3rd party processor.

Example HTMLElement added to DOM:

<iframe height="0" width="0" frameborder="0" allowtransparency="true" scrolling="no" src="https://www.3rdpartytracker.com?dataSubjectRequest=eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczpcL1wvd3d3LjNyZHBhcnR5dHJhY2tlci5jb20iLCJkc3IiOnsidHlwZSI6IkFDQ0VTUyIsInZlcnNpb24iOiIxIiwidGFyZ2V0IjoiaHR0cHM6XC9cL2FwaS5wcm9jZXNzb3Iub2F0aC5jb21cL3YxXC9kYXRhU3ViamVjdFJlcXVlc3RcL2QzZDNMak55WkhCaGNuUjVkSEpoWTJ0bGNpNWpiMjA9XC9tYXRlcmlhbCJ9LCJpc3MiOiJnZHByLWNvcmUiLCJjbmYiOnsia2lkIjoiMkM6QzI6MEQ6NUU6NDI6QUY6RUY6QTM6QUQ6RTk6QjU6NjI6NTk6NTg6Qjg6MUQ6RTU6QTM6QTYifSwiZXhwIjoxNTM0MDExMzYwLCJpYXQiOjE1MzE0MTkzNjAsImp0aSI6IjA2MTkwZmI2LTI1NjMtNGNmNi04MDViLTA4OGIzNmIwYTcxMCJ9.a1Wu1gSboNcyJSdEM8wX597XGLoi3Di994qQSXOfpIqNqdArRxYBhcLcV-CN405_gDA5-mnPsYtzyZt2HFIQW_26lqZgio7_ULGPunuWATsKkHSzV3wCLgAXssSuWO1TVerSV76VlTi7HByP285POXMENqL9EuMdaChMSvwj3AuvMZeZdwAC2oGMo3CiQ_J1D1aywZ2-abmycliZcYfW3RMIeYs6iMOt4tSxlIvh6lNqiE-r5AVZk9sYTGakvLWSDoZUN3a_dUaU1jt2Oi3QhoX2yqrW0H-IJDOM5CyvclTWrlpAmDSxKdbQaYLB7vmkvxvGTFItZQfCNq0t_FB-9A&lang=en-US"></iframe>

ServerSide

Description:

This implementation is exclusively for those processor(s) which use an id that is shared with Verizon Media, and store data pertaining to a data subject. This is the only implementation which will utilize the optional ident claim, and this claim will contain the shared id. This call must return a 200 http response to signifiy that they have receieved the request. Any other http response will result in a retry from Verizon Media until this response is provided. This response does not and should not contain the data for the subject, (which should be returned as described above) but exclusively acknowledges that the request was received.

Example Http call:

https://www.<registered_uri>?dataSubjectRequest=eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczpcL1wvd3d3LjNyZHBhcnR5dHJhY2tlci5jb20iLCJkc3IiOnsidHlwZSI6IkFDQ0VTUyIsInZlcnNpb24iOiIxIiwidGFyZ2V0IjoiaHR0cHM6XC9cL2FwaS5wcm9jZXNzb3Iub2F0aC5jb21cL3YxXC9kYXRhU3ViamVjdFJlcXVlc3RcL2QzZDNMak55WkhCaGNuUjVkSEpoWTJ0bGNpNWpiMjA9XC9tYXRlcmlhbCJ9LCJpZGVudCI6IntcInN1YmplY3RJZFwiOlwiam9lLnVzZXJcIn0iLCJpc3MiOiJnZHByLWNvcmUiLCJjbmYiOnsia2lkIjoiMkM6QzI6MEQ6NUU6NDI6QUY6RUY6QTM6QUQ6RTk6QjU6NjI6NTk6NTg6Qjg6MUQ6RTU6QTM6QTYifSwiZXhwIjoxNTM0MDExMzYwLCJpYXQiOjE1MzE0MTkzNjAsImp0aSI6IjIzYTZkYTE2LTc4ZmQtNGUyMC1iNWQ5LTZiOGRhMjcyYjJhZSJ9.IcVShvchWRxki9xXak8Q16zPdY2e54nJFrkSWW-qrF6cdFWsx_6g54YhEQlF7ZfwCHLEw-Pp7nZk-3Ug5ROU_hPlsiGuYM_unrn2kPGLjzi6evzK8ZqL0SPVBCbnfMkw9TOlNm6QBQdbHVrLUfpfJvR78GDuWdASDccKs2lm5Uz_7YMry01hM98u9JQZwaytgYvBx_Jn19NGQOFNP_QQ71LBTctdVFyUm1m7tygsuajQtT8-BcfGCAWQD7NPTi6oIEkStsNWujeGQjUtSeyxoH3Nyh8OjiqbI_byw6P03qBhB8QL6PoNsfrrHRFHtfoGwN_7LL9GO2BYfyB0ebFAhQ