Getting Started with the Consent Files Service API
Instructions on getting and using access tokens to make authenticated API calls. Once you have your token, see List Consent Files for endpoint information.
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 | Format | 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 | Format | 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 |
Updated over 1 year ago