|
| 1 | +--- |
| 2 | +title: UID2 Tokens and Refresh Tokens |
| 3 | +description: Information for publishers about UID2 tokens and refresh tokens. |
| 4 | +hide_table_of_contents: false |
| 5 | +sidebar_position: 06 |
| 6 | +--- |
| 7 | + |
| 8 | +import Link from '@docusaurus/Link'; |
| 9 | + |
| 10 | +# UID2 Tokens and Refresh Tokens |
| 11 | + |
| 12 | +When a publisher sends a user's <Link href="../ref-info/glossary-uid#gl-dii">DII</Link>—hashed or unhashed email addresses or phone numbers—to the UID2 Operator, whether via one of the UID2 SDKs or the [POST /token/generate](../endpoints/post-token-generate.md) endpoint, the UID2 Operator converts the DII to a <a href="glossary-uid#gl-raw-uid2">raw UID2</a>, encrypts it into a <a href="glossary-uid#gl-uid2-token">UID2 token</a>, and returns the UID2 token with associated values, including a refresh token. The publisher can then use the UID2 token in the bidstream. |
| 13 | + |
| 14 | +## UID2 Tokens: Key Information |
| 15 | + |
| 16 | +Here are some key points about UID2 tokens: |
| 17 | + |
| 18 | +- The UID2 token is a unique value: no two UID2 tokens are the same. |
| 19 | +- UID2 tokens are case sensitive. |
| 20 | +- The token value is an <a href="glossary-uid#gl-opaque">opaque</a> string: do not make any assumptions about the format or length of the string. |
| 21 | +- 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. |
| 22 | +- 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](../getting-started/gs-opt-out.md). |
| 23 | +- The token has a limited life, but can be refreshed using the refresh token. |
| 24 | +- 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. |
| 25 | +- 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. |
| 26 | +- Publishers send UID2 tokens in the bidstream. |
| 27 | +- Refreshing a UID2 token does not invalidate/expire the original or previous UID2 token. You can still use the earlier token until it expires. |
| 28 | + |
| 29 | +## Refresh Tokens: Key Information |
| 30 | + |
| 31 | +Here are some key points about refresh tokens: |
| 32 | + |
| 33 | +- A refresh token is a string that is issued along with the <a href="glossary-uid#gl-uid2-token">UID2 token</a>. |
| 34 | +- Refresh tokens are case sensitive. |
| 35 | +- The token value is an <a href="glossary-uid#gl-opaque">opaque</a> string: do not make any assumptions about the format or length of the string. |
| 36 | +- You can use the refresh token to generate a new UID2 token and new refresh token before the current refresh token expires. |
| 37 | +- Using refresh tokens is optional: you could choose to generate a new token from DII each time rather than refreshing an existing token. |
| 38 | +- You can manage token refresh in a variety of ways, such as: |
| 39 | + - With a UID2 SDK (see [SDK Functionality](../sdks/summary-sdks.md#sdk-functionality)) |
| 40 | + - By calling the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint |
| 41 | + - By using the UID2 Prebid.js module (see [UID2 Integration Overview for Prebid.js](../guides/integration-prebid.md)) |
| 42 | +- When a new UID2 token is generated and returned in response to the refresh token, a new refresh token is returned along with it. |
| 43 | +- 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](../sdks/summary-sdks.md#sdk-functionality) (*Refresh UID2 Token* column). |
| 44 | +- 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](../getting-started/gs-opt-out.md). |
| 45 | + |
| 46 | +### Recommended Token Refresh Frequency |
| 47 | + |
| 48 | +The recommended refresh interval is hourly. |
| 49 | + |
| 50 | +To determine when to refresh, you can use the timestamp of the `refresh_from` field in the response to the [POST /token/generate](../endpoints/post-token-generate.md) endpoint (see [Successful Response](../endpoints/post-token-generate.md#successful-response)) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint (see [Successful Response With Tokens](../endpoints/post-token-refresh.md#successful-response-with-tokens)). The value of this field is a timestamp in UNIX time, expressed in milliseconds. |
| 51 | + |
| 52 | +## FAQs |
| 53 | + |
| 54 | +There are some frequently asked questions relating to token refresh: see [FAQs for Publishers](../getting-started/gs-faqs.md#faqs-for-publishers). |
0 commit comments