Skip to main content

UID2 Tokens and Refresh Tokens

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

UID2 Tokens: Key Information​

Here are some key points about UID2 tokens:

  • The UID2 token is a unique value: no two UID2 tokens are the same.
  • UID2 tokens are case sensitive.
  • The token value is an opaque string: do not make any assumptions about the format or length of the string.
  • UID2 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 UID2.
  • The token generation logic checks for user opt-out. If the user has opted out of UID2, no UID2 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 UID2 token and corresponding new refresh token, as long as the current UID2 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 UID2 token from the original hashed or unhashed email address or phone number.
  • Publishers send UID2 tokens in the bidstream.
  • Refreshing a UID2 token does not invalidate/expire the original or previous UID2 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 UID2 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 UID2 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 DII each time rather than refreshing an existing token.
  • You can manage token refresh in a variety of ways, such as:
  • When a new UID2 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 UID2 Token column).
  • When the UID2 Operator Service receives the refresh token with a request for a new UID2 token, it checks for user opt-out. If the user has opted out of UID2, no new UID2 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 UID2 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 UID2 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.