Skip to main content

Trust Tokens is a new API to help fight fraud and distinguish bots from real humans, without passive tracking.


It appears in:
Safe and secure


Trusted tokens allow an origin to issue cryptographic tokens to a trusted user. The tokens are stored by the user's browser. The browser can use the tokens in other contexts to assess the authenticity of the user.

The Trust Token API allows a user's trust in one context (such as to be passed to another context (such as an ad running on without identifying the user or linking the two identities.

Why do we need Trust Tokens?

The web needs ways to establish trust signals that show that a user is who they claim to be, and not a bot pretending to be a human, or a malicious third party defrauding a real person or service. Protection against fraud is particularly important for advertisers, ad providers, and CDNs.

Unfortunately, many of the existing mechanisms for measuring and propagating trustworthiness (to determine if an interaction with a site is from a real human being, for example) take advantage of techniques that can also be used for fingerprinting.

Key term:
Fingerprints allows sites to identify and track individual users by obtaining data about their device, operating system, and browser settings (such as language preferences,
user agentand available fonts) or changes in device status. This can be done on the server by checking the request headers or on the client with JavaScript.

Fingerprinting uses mechanisms that users are not aware of and cannot control. Sites like Panopticon and show how fingerprint data can be combined to identify you as an individual.

The API must preserve privacy, allowing trust to spread across sites without tracking individual users.

What's in the Trust Tokens Proposal?

The web is based on generating trust signals to detect fraud and spam. One way to do this is by tracking navigation with global per-user identifiers between sites. For an API that preserves privacy, that is not acceptable.

Of the proposal

This API proposes a new storage area by origin for "Privacy Pass" style cryptographic tokens, which are accessible in third-party contexts. These tokens are not personalized and cannot be used to track users, but they are cryptographically signed so they cannot be forged.

When an origin is in a context where they trust the user, they can issue a batch of tokens to the browser, which can be "spent" at a later time in a context where the user would be unknown or less trusted. Fundamentally, tokens are indistinguishable from each other, preventing websites from tracking users through them.

In addition, we propose an extension mechanism for the browser to sign outgoing requests with keys linked to a particular token redemption.

Sample API usage

The following is an adaptation of
sample code in api explainer.

Imagine that a user visits a news website (publisher.example) that incorporates advertising from a third-party advertising network (foo.example). User has previously used a social media site that issues trust tokens (issuer.example).

The following sequence shows how trusted tokens work.

1. The user visits issuer.example.

2. issuer.example verifies that the user is a human and executes the following JavaScript:

fetch ( 'https: //issuer.example/issue' , {
trustToken : {
type : 'token-request'
} ) ;

3. The user's browser stores the trust tokens associated with issuer.example.

4. Some time later, the user visits publisher.example.

5. publisher.example wants to know if the user is a human, so they ask
issuer.example executing the following JavaScript:

fetch ( 'https: //issuer.example/redeem' , {
trustToken : {
type : 'srr-token-redemption'
} ) ;

With this code:

  1. The browser requests a redemption.
  2. The issuer returns a Signed Redemption Record (SRR) indicating that they ever issued a valid token for this browser.
  3. When the returned promise is resolved, the SRR can be used in subsequent resource requests.

6. publisher.example then you can run the following JavaScript in a top-level document:

fetch ( 'foo.example / get-content' , {
trustToken : {
type : 'send-srr' ,
issuer : 'https: //issuer.example'
} ) ;

With this code:

  1. foo.example you get the SRR, and now you have some indication that
    issuer.example thought this user was human.
  2. foo.example respond accordingly.

You may have purchase history with an e-commerce site, records on a location platform, or account history with a bank. Issuers can also consider other factors, such as how long you've had an account or other interactions (such as CAPTCHA or form submission) that increase the issuer's confidence in the likelihood that it is a real human being.

Issuance of trusted tokens

If a trusted token issuer considers the user to be trustworthy, such as
issuer.example, the issuer can obtain trusted tokens for the user by doing a
fetch () request with a new trustToken parameter:

fetch ( 'issuer.example / .well-known / trust-token' , {
trustToken : {
type : 'token-request' ,
issuer : < issuer >
} ) . then ( ... )

This invokes an extension of the Privacy pass broadcast protocol using a new crypto primitive:

  1. Generate a set of pseudo-random numbers known as nonces.

  2. Blind the nonces (encode them so that the issuer cannot see their content) and attach them to the request in a Sec-Trust-Token header.

  3. Send a POST request to the endpoint provided.

The endpoint responds with blinded tokens (signatures on the blind nonces), then the tokens are unmasked and the browser stores them internally along with the associated nonces as trusted tokens.

Redemption of trusted tokens

A publisher site (like publisher.example in the example above) you can check if there are trust tokens available to the user:

const userHasTokens = await document . hasTrustToken ( < issuer > ) ;

If tokens are available, the publisher's site can redeem them to obtain a signed redemption record:

fetch ( 'issuer.example / .well-known / trust-token' , {
trustToken : {
type : 'srr-token-redemption' ,
issuer : 'issuer.example' ,
refreshPolicy : 'none'
} ) . then ( ... )

The publisher site can then send the SRR to the requests it makes using the following API:

fetch ( ' ' , {
trustToken : {
type : 'send-srr' ,
issuer : < issuer > ,
} ) . then ( ... ) ;

The publisher must include the SRR in requests that require a trust token, such as posting a comment, liking a page, or voting in a poll.

Trusted tokens are only accessible through Fetch, XHR, and HTML options