## Sample API usage The following is adapted from [sample code in the API explainer](https://github.com/WICG/trust-token-api#sample-api-usage). The code in this post uses updated syntax available since Chrome 88. Imagine that a user visits a news website (`publisher.example`) which embeds advertising from a third party ad network (`foo.example`). The user has previously used a social media site that issues trust tokens (`issuer.example`). The sequence below shows how trust tokens work. **1.** The user visits `issuer.example` and performs actions that lead the site to believe they are a real human, such as account activity, or passing a CAPTCHA challenge. **2.** `issuer.example` verifies the user is a human, and runs the following JavaScript to issue a trust token to the user's browser: ```js fetch('https://issuer.example/trust-token', { trustToken: { type: 'token-request', issuer: 'https://issuer.example' } }).then(...) ``` **3.** The user's browser stores the trust token, associating it with `issuer.example`. **4.** Some time later, the user visits `publisher.example`. **5.** `publisher.example` wants to know if the user is a real human. `publisher.example` trusts `issuer.example`, so they check if the user's browser has valid tokens from that origin: ```js document.hasTrustToken('https://issuer.example'); ``` **6.** If this returns a promise that resolves to `true`, that means the user has tokens from `issuer.example`, so `publisher.example` can attempt to redeem a token: ```js fetch('https://issuer.example/trust-token', { trustToken: { type: 'token-redemption', issuer: 'https://issuer.example', refreshPolicy: {none, refresh} } }).then(...) ``` With this code: 1. The redeemer `publisher.example` requests a redemption. 1. If the redemption is successful, the issuer `issuer.example` returns a redemption record which indicates that at some point they issued a valid token to this browser. **7.** Once the promise returned by `fetch()` has resolved, the redemption record can be used in subsequent resource requests: ```js fetch('https://foo.example/get-content', { trustToken: { type: 'send-redemption-record', issuers: ['https://issuer.example', ...] } }); ``` With this code: 1. Redemption records are included as a request header `Sec-Redemption-Record`. 1. `foo.example` receives the redemption record and can parse the record to determine whether `issuer.example` thought this user was a human. 1. `foo.example` responds accordingly. How can a website work out whether to trust you? You might have shopping history with an e-commerce site, check-ins on a location platform, or account history at a bank. Issuers might also look at other factors such as how long you've had an account, or other interactions (such as CAPTCHAs or form submission) that increase the issuer's trust in the likelihood that you're a real human. ### Trust token issuance If the user is deemed to be trustworthy by a trust token issuer such as `issuer.example`, the issuer can fetch trust tokens for the user by making a `fetch()` request with a `trustToken` parameter: ```js fetch('issuer.example/trust-token', { trustToken: { type: 'token-request' } }).then(...) ``` This invokes an extension of the [Privacy Pass](https://privacypass.github.io/) issuance protocol using a [new cryptographic primitive](https://eprint.iacr.org/2020/072.pdf): 1. Generate a set of pseudo-random numbers known as _nonces_. 1. Blind the nonces (encode them so the issuer can't view their contents) and attach them to the request in a `Sec-Trust-Token` header. 1. Send a POST request to the endpoint provided. The endpoint responds with [blinded tokens](https://en.wikipedia.org/wiki/Blind_signature) (signatures on the blind nonces), then the tokens are unblinded and stored internally together with the associated nonces by the browser as trust tokens. ### Trust token redemption A publisher site (such as `publisher.example` in the example above) can check if there are trust tokens available for the user: ```js const userHasTokens = await document.hasTrustToken('issuer.example/trust-token'); ```` If there are tokens available, the publisher site can redeem them to get a redemption record: ```js fetch('issuer.example/trust-token', { ... trustToken: { type: 'token-redemption', refreshPolicy: 'none' } ... }).then(...) ``` The publisher can include redemption records in requests that require a trust token—such as posting a comment, liking a page, or voting in a poll—by using a `fetch()` call like the following: ```js fetch('https://foo.example/post-comment', { ... trustToken: { type: 'send-redemption-record', issuers: ['issuer.example/trust-token', ...] } ... }).then(...); ``` Redemption records are included as a `Sec-Redemption-Record` request header. Trust tokens are only accessible through options to Fetch, XHR, and the HTML `This API proposes a new per-origin storage area for "Privacy Pass" style cryptographic tokens, which are accessible in third party contexts. These tokens are non-personalized and cannot be used to track users, but are cryptographically signed so they cannot be forged.
When an origin is in a context where they trust the user, they can issue the browser a batch of tokens, which can be "spent" at a later time in a context where the user would otherwise be unknown or less trusted. Crucially, the tokens are indistinguishable from one another, preventing websites from tracking users through them.
We further propose an extension mechanism for the browser to sign outgoing requests with keys bound to a particular token redemption.