Skip to main content

EUID Tokens and Refresh Tokens

When a publisher sends a user's personal data—hashed or unhashed email addresses or phone numbers—to the EUID Operator, whether via one of the EUID SDKs or the POST /token/generate endpoint, the EUID Operator converts the personal data to a raw EUID, encrypts it into an EUID token, and returns the EUID token with associated values, including a refresh token. The publisher can then use the EUID token in the bidstream.

EUID Tokens: Key Information​

Here are some key points about EUID tokens:

  • The EUID token is a unique value: no two EUID tokens are the same.
  • EUID tokens are case sensitive.
  • The token value is an opaque string: do not make any assumptions about the format or length of the string.
  • EUID tokens representing different instances of user activity, on browsers, CTV, and electronic devices such as phones and tablets, can still be matched to the same raw EUID.
  • The token generation logic checks for user opt-out. If the user has opted out of EUID, no EUID token is generated. For details, see User Opt-Out.
  • The token has a limited life, but can be refreshed using the refresh token.
  • You can refresh many times, to get a new EUID token and corresponding new refresh token, as long as the current EUID token is always refreshed before the current refresh token expires.
  • If the token has expired, or as an alternative to refreshing an existing token, you can generate a new EUID token from the original hashed or unhashed email address or phone number.
  • Publishers send EUID tokens in the bidstream.
  • Refreshing an EUID token does not invalidate/expire the original or previous EUID token. You can still use the earlier token until it expires.

Refresh Tokens: Key Information​

Here are some key points about refresh tokens:

  • A refresh token is a string that is issued along with the EUID token.
  • Refresh tokens are case sensitive.
  • The token value is an opaque string: do not make any assumptions about the format or length of the string.
  • You can use the refresh token to generate a new EUID token and new refresh token before the current refresh token expires.
  • Using refresh tokens is optional: you could choose to generate a new token from personal data each time rather than refreshing an existing token.
  • You can manage token refresh in a variety of ways, such as:
  • When a new EUID token is generated and returned in response to the refresh token, a new refresh token is returned along with it.
  • In most cases, you can refresh tokens on the client side, even if the token was generated on the server side. For details about refresh functionality for the various SDKs, see SDK Functionality (Refresh EUID Token column).
  • When the EUID Operator Service receives the refresh token with a request for a new EUID token, it checks for user opt-out. If the user has opted out of EUID, no new EUID token is generated. For details, see User Opt-Out.

Currently, the recommended refresh interval is hourly. An hourly interval helps ensure that the token doesn't get close to being expired, and is ready to be sent to the bidstream. In addition, since user opt-out is checked before a new token is generated, this helps ensure that user opt-out preferences are implemented promptly.

To determine when to refresh, you can use the timestamp of the refresh_from field in the response to a call to one of the following EUID API endpoints:

The refresh_from field is a Unix timestamp, and the value is one hour from the time that the token was generated, expressed in milliseconds.

tip

The recommended refresh interval could change in the future. Rather than using a fixed value, it's best to calculate based on the refresh_from value.

Managing Token Refresh with an SDK​

An easy way to manage token refresh is to use one of the EUID SDKs that have a function for the purpose: either the Java or Python SDK.

Each of these SDKs includes a publisher class that has a function to determine if a token refresh is needed.

The following examples show how you could first check if the token can be refreshed and then check if refresh is needed, using one of these SDKs. If it's time to refresh, you can then call the refresh function to refresh the token.

  1. Determine if the identity can be refreshed (that is, the refresh token hasn't expired):

    if (identity == null || !identity.isRefreshable()) { we must no longer use this identity (for example, remove this identity from the user's session) }

  2. Determine if a refresh is needed:

    if (identity.isDueForRefresh()) {..}

Before using the code example, check the prerequisites and notes for the language you're using. For details, refer to the doc for the applicable SDK:

FAQs​

There are some frequently asked questions relating to token refresh: see FAQs for Publishers.