POST /token/generate
Requests an EUID token generated from a user's personal data (email address). If the email address is valid, and the user has not opted out of EUID, this operation returns an EUID token and associated values.
Used by: This endpoint is used mainly by publishers.
Be sure to call this endpoint only when you have a legal basis to convert the user’s personal data to an EUID token for targeted advertising. The optout_check
parameter, required with a value of 1
, checks whether the user has opted out.
Rather than calling this endpoint directly, you could use one of the SDKs to manage it for you. For a summary of options, see SDKs: Summary.
Request Format
POST '{environment}/v2/token/generate'
Here's what you need to know about this endpoint requests:
- To ensure that the API key used to access the service remains secret, EUID tokens must be generated only on the server side after authentication.
- You must encrypt all requests using your secret. For details, and code examples in different programming languages, see Encrypting Requests and Decrypting Responses.
Path Parameters
Path Parameter | Data Type | Attribute | Description |
---|---|---|---|
{environment} | string | Required | Testing (integration) environment: https://integ.euid.eu Production environment: https://prod.euid.eu For a full list, including regional operators, see Environments. Notes:
|
Unencrypted JSON Body Parameters
You must include only one of the following two conditional parameters, plus the required optout_check
parameter with a value of 1
, as key-value pairs in the JSON body of the request when encrypting it.
Body Parameter | Data Type | Attribute | Description |
---|---|---|---|
email | string | Conditionally Required | The email address for which to generate tokens. |
email_hash | string | Conditionally Required | The Base64-encoded SHA-256 hash of a normalized email address. |
tcf_consent_string | string | Optional | The Transparency and Consent String from the end user whose identity is used to generate the token. |
optout_check | number | Required | Checks whether the user has opted out. Include this parameter with a value of 1 . |
Request Examples
To ensure that the API key used to access the service remains secret, the POST /token/generate
endpoint must be called from the server side, unlike the POST /token/refresh, which does not require using an API key.
The following are unencrypted JSON request body examples for each parameter, one of which you should include in your token generation requests:
{
"email": "username@example.com",
"optout_check": 1
}
{
"email_hash": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"optout_check": 1
}
Here's an encrypted token generation request format with placeholder values:
echo '[Unencrypted-JSON-Request-Body]' \
| encrypt_request.py [CLIENT_SECRET] \
| curl -X POST 'https://prod.euid.eu/v2/token/generate' -H 'Authorization: Bearer [CLIENT_API_KEY]' -d @- \
| decrypt_response.py [CLIENT_SECRET]
Here's an encrypted token generation request example for an email hash:
echo '{"email_hash": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="}' \
| encrypt_request.py DELPabG/hsJsZk4Xm9Xr10Wb8qoKarg4ochUdY9e+Ow= \
| curl -X POST 'https://prod.euid.eu/v2/token/generate' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' -d @- \
| decrypt_response.py DELPabG/hsJsZk4Xm9Xr10Wb8qoKarg4ochUdY9e+Ow=
For details, and code examples in different programming languages, see Encrypting Requests and Decrypting Responses
Decrypted JSON Response Format
The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted.
This section includes the following sample responses:
Successful Response
A successful decrypted response returns the user's advertising and refresh tokens for the specified email address or email address hash.
{
"body": {
"advertising_token": "E4AAAABl85Pd1yKbznQL58Q_09bAJtGbGl2e-JCLPLGUSsz7ao6iR11QySi-kLtJ7suJAn3lK474gJvOLVK0_BZe8FABStV44hHWoFt9IfWVj35PIWQJ8VoJzrmHhh6YyQDtQ3q_t0ZJL9OjB8cXa94dMDhlGzi3j5K4o9cH3X1OYgJFQDat4L2cj7HMptpWUO9dheldwpVhgfAlLdEw9D3xtA",
"identity_expires": 1724998239163,
"refresh_expires": 1725081039163,
"refresh_from": 1724995539163,
"refresh_response_key": "JZcp6vMDhuMUPAA03QnsW74MhNn4Ng37XRCNChyeX2k=",
"refresh_token": "EAAAAGb41t8MrmTpHpDWYi67K8ok7qo87IQwan5Ghz4CGPz3pYXCoS/bAEygLYa0tjMPw6v1q2UsjQQ7SURA6tq7VvTdROOkxJ6YcNiaCeCpINoZYT5xzsPp9VgkkWT0HkxLYdMUt3M7KMJ+gziJQZGsoMeEYTMR3yEO5w+A7N1uW71Q7PWyTJaRab7F0hUdmwHwN9ZdDj/+Ky/qzf8YBGPzSWvpN7Ry9gT6EQxVZSZIj6PSzFxvSPVt48i59VpJ6zvOL4MKCAtiAFZ92DUeKfGYZ3XptcbO2srOFaAgeJm2hiSOKWPxYfhCBPZa2yYbKRc+UFNO7L+UnxlL+VRU1GTZm3zncDpXlif1lqmfXuza+KMXQmPzuhzxljn0nkUBa8OC"
},
"status": "success"
}
Optout
Here is an example response when the user has opted out.
{
"status": "optout"
}
Response Body Properties
Property | Data Type | Description |
---|---|---|
advertising_token | string | An encrypted advertising (EUID) token for the user. |
refresh_token | string | An encrypted token that can be exchanged with the EUID Service for the latest set of identity tokens. |
identity_expires | number | The Unix timestamp (in milliseconds) that indicates when the advertising token expires. |
refresh_from | number | The Unix timestamp (in milliseconds) that indicates when the SDK for JavaScript (see SDK for JavaScript Reference Guide) will start refreshing the EUID token. TIP: If you are not using the SDK, consider refreshing the EUID token from this timestamp, too. |
refresh_expires | number | The Unix timestamp (in milliseconds) that indicates when the refresh token expires. |
refresh_response_key | string | A key to be used in a POST /token/refresh request for response decryption. |
Response Status Codes
The following table lists the status
property values and their HTTP status code equivalents.
Status | HTTP Status Code | Description |
---|---|---|
success | 200 | The request was successful. The response will be encrypted. IMPORTANT: This status may be returned without a generated token. For example, if the tcf_consent_string parameter value is included, but does not contain sufficient information to generate a token, an insufficient_user_consent message is returned. |
optout | 200 | The request was successful. Could not generate token because the user has opted out. |
client_error | 400 | The request had missing or invalid parameters, including an invalid tcf_consent_string value. |
unauthorized | 401 | The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested operation. |
If the status
value is anything other than success
, the message
field provides additional information about the issue.
Test Identities
Type | Identity | Purpose | Next Endpoint |
---|---|---|---|
validate@example.com | Test that the advertising_token you've cached matches the advertising_token for the specified email address. | POST /token/validate | |
optout@example.com | Using this email for the request always generates an optout response. | POST /token/generate | |
refresh-optout@example.com | Using this email for the request always generates an identity response with a refresh_token that results in an optout response. | POST /token/refresh |