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.

Response	Error
200	None
400	Bad Request
401	Unauthenticated User
422	Input Validation Error

Consent File Schema

denotes required

Name	Type	Description	Format	Example
id*	string	Unique identifier for the Consent File resource	uuid	C0442751-D144-493D-A40C-A408588F929A
identifierType*	string	Type of identifiers in the Consent File.	enum ["IDENTITYLINK", "COOKIE", "MUID", "CUSTOM_ID", "HPI", "RAMPID"]	MUID
muidDeviceType	string	(For MUID identifierType) the type of mobile device. MIXED is a superset of the others	enum ["AAID", IDFA", "MIXED"]	IDFA
muidFormat	string	(For MUID identifierType) the format of the identifier values	enum ["RAW", "HASHED"]	RAW
requestType*	string	Type of request, indicating how the receiver should handle the consent information	enum ["OPT_OUT", "DELETE"]	OPT_OUT
dataController*		see "Data Controller Schema"
fileURL*	string	Time-limited, signed URL to access the file	un
createdAt*	string	File creation timestamp in UTC, ISO-8601 compliant	date-time	2019-11-26T21:37:19Z

Data Controller Schema

Denotes Required

Name	Type	Description	Example
controllerSpecifier	string	Type of specifier used to identify the controller	SEAT_ID
controllerID	string	Actual identifier for the controller	E334032B-F985-4017-B273-7B5704E8AD30
liverampControlled*	boolean	Flag that indicates whether LiveRamp is a controller	false

Errors Schema

Denotes Required

Name	Type	Description	Example
httpStatuscode*	integer	The HTTP error status code for this problem
message*	string	Human readable error message
errorCode	string	Optional, more granular error code for this problem	BAD_HEADER_PARAMETER