Getting Started with the Consent Files Service API

Getting Credentials

We will send you an email that contains a link for you to get your API credentials via LastPass. The credentials file will look like this:

```
{
  "type": "serviceAccount/v2",
  "uid": "00u1nmeo9zo99s233357",
  "account_id": "[email protected]",
  "secret_key": "vdmAe8Pzxf6lW5-tYEeqmKbV167NCnkdhUqs-KBg1t4",
  "client_id": "liveramp-api",
  "token_uri": "https://sso.liveramp.com/oauth2/default/v2/token"
}
```

Getting an Access Token

In order to authenticate with the Consent Files Services API, you will need to pass a valid access token in the header of the request. To get an access token you will have to hit the token endpoint and provide the account_id and secret_key from your credentials file. You can use jq to get these fields:

TOKEN_URI=$(cat credentials.json | jq -r .token_uri)
SERVICE_USER_EMAIL=$(cat credentials.json | jq -r .account_id)
SERVICE_USER_PASSWORD=$(cat credentials.json | jq -r .secret_key)

Here is an example of a request to the token endpoint:

curl https://sso.liveramp.com/oauth2/default/v2/token \
  -d grant_type=password \
  -d username="$SERVICE_USER_EMAIL" \
  -d password="$SERVICE_USER_PASSWORD" \
  -d scope=openid \
  -d client_id="liveramp-api" \
  -d response_type=token

If your request is successful, the JSON response will include an access token. For example:

```
{
    "access_token": "eyJraWQiOiJnNmpGeEdlSmdYMm1TLU5oMmp6US1EM0EzaF9FVVhxcXdCRVBZcU1iaFhzIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULmZXdVhpNWxoekxZOTBEVHBMTG9fN01FbDB4eUJ1em9mYWIxaTRpRjlQM3ciLCJpc3MiOiJodHRwczovL3Nzby5saXZlcmFtcC5jb20vb2F1dGgyL2RlZmF1bHQiLCJhdWQiOiJhcGk6Ly9kZWZhdWx0IiwiaWF0IjoxNTcyMDM2NDM3LCJleHAiOjE1NzIwMzcwMzcsImNpZCI6ImxpdmVyYW1wLWFwaSIsInVpZCI6IjAwdTFvMnBsc2h0amRxZW4yMzU3Iiwic2NwIjpbIm9wZW5pZCJdLCJzdWIiOiJuaWNrcy1qdW5rLXE5emRxMzMxQHNlcnZpY2VhY2NvdW50cy5saXZlcmFtcC5jb20ifQ.HWPEhpq7pWRkaAOG_ooLWGcX_hxZXEcuupHnA7vcvpgjMl1fctSyaSYOnE77stv9mJvlg422MV23p85qNw-6u8doS_U1TZB5Ok9OAg4S-gncurjTs_cpd0pSNa1oUjMz0Ak052Zqrwkt2dNAO6dUDLAOVCwEyectRlVTPb40yDY3M6vGb3Y_KGImIxJ1MesN4wZO4GvgHb7w7FWBv0AWXuIcitmaIH8oeBPG5gfJXxyRF3lFdaFONZ5aH-SSwXIo-l3C3N0Um4tRyQN1Y8u2bETJHtGs2t8B2eHZ29zKxt_tGb-cTV8iAhGyHbt8SnGDNhOF30VfxIx2YiFtlsqgKw",
    "expires_in": 600,
    "id_token": "eyJraWQiOiJnNmpGeEdlSmdYMm1TLU5oMmp6US1EM0EzaF9FVVhxcXdCRVBZcU1iaFhzIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIwMHUxbzJwbHNodGpkcWVuMjM1NyIsInZlciI6MSwiaXNzIjoiaHR0cHM6Ly9zc28ubGl2ZXJhbXAuY29tL29hdXRoMi9kZWZhdWx0IiwiYXVkIjoibGl2ZXJhbXAtYXBpIiwiaWF0IjoxNTcyMDM2NDM3LCJleHAiOjE1NzIwNDAwMzcsImp0aSI6IklELmNBVnljOW9rVktKa3UtOGp3X2ZqQTRibF9BdWhOMWN0cW5IU3RHRFZEQXciLCJhbXIiOlsicHdkIl0sImlkcCI6IjAwbzEzb25wZXROVzNSZHo1MzU3IiwiYXV0aF90aW1lIjoxNTcyMDM2NDM3LCJhdF9oYXNoIjoiejg4TzFxZWloZDBGSjc4ZDBaakVzZyJ9.gpVrt-Lx3EGFGIA0Ucr_6_WGZHMqyV_Q_Oe0JTTn00M69sAudJ7DYnbQPWcECA8cRCczOl2wMTMqrUZC9Mq8Fe_KHPJc1JukD4DKl7IoZZrJr5_dBzz0xhSxBkq1nqz9SQoUk425QHrIIuTrsaR8J6ch6Jb6QkmQ8BrcstMJWG1oOy3EJkpOAAVmMnpcl_UUrMN-TPc9DsAwOFkBWaspJdInLEtwpAeXpRF2wDZiuHgGlTK4t2pe6Y_GWeXWvXR94lHuTw_rQuXQj7BitqLnCeY_BO0XzxkGX326jYfqoBMXOew-_SXq77WyQIBSVdjiB-gt9yrkKcWiVo52dvrymg",
    "scope": "openid",
    "token_type": "Bearer"
}
```

Using Your Access Token

You need to include an access token in the header of every request. Use the Oauth2 standard bearer token format.
For example:

curl --request GET --url 'https://api.liveramp.com/privacy/v2/consent-files' --header 'accept: application/json' --header 'Authorization: Bearer $MY_ACCESS_TOKEN'

Access Token Expiration

Access tokens expire after 10 minutes and each one should be reused until it is close to expiring.
The access token is a base64-encoded JWT. An access token's expiration time can be checked by decoding its payload.
See these docs for more information.

Authentication Errors

If you receive a 401 Unauthorized error while attempting to fetch an access token, there was a problem with the credentials you provided. Ensure that your credentials are correct. If the problem persists, please reach out to your account team.
If you receive a 401 Unauthorized error while attempting to hit an authenticated API, your access token was likely expired.

Consent File Schema

• denotes required

Data Controller Schema

• Denotes Required

Errors Schema

• Denotes Required