ThePrivate State Token API provides a mechanism for conveying trust in a user's authenticity from one browsing context to another, without sharing the user's identity or allowing their activity across websites to be tracked.

Concepts and usage

To prevent fraud on the web, websites and services need to establish and convey trust signals that prove a user is who they say they are, and is not a bot pretending to be a human or a malicious third party defrauding a real person or service.

• Trust is established using mechanisms such asCAPTCHAs, verifying email addresses, or making purchases.
• Trust is traditionally conveyed between different origins using mechanisms such asthird-party cookies.

Unfortunately, current cookie-based techniques for conveying such information are not secure and can be used forfingerprinting and tracking users, which is problematic for user privacy.

Private state tokens solve this problem, allowing trust signals to be conveyed across origins without passive tracking using thePrivacy Pass protocol in the background.

How do private state tokens work?

1. When a website has established trust in a user (for example via a CAPTCHA), it can issue a cryptographic token that is stored securely by the user's browser. This website is called anissuer.
2. Another website can then verify that the same user is trustworthy by checking if their browser has a token stored that was issued by an issuer that the website trusts. If so, they can redeem that token to get aredemption record. This website is called aredeemer.
3. The redemption record is then used to give the user access to services as if they were authenticated directly with that site, and can also be forwarded onto other parties to convey trust.

Private state tokens are encrypted, so it isn't possible to identify an individual or connect trusted and untrusted instances to discover user identity.

SeeUsing the Private State Token API for a guide to using private state tokens.

Interfaces

The Private State Token API has no distinct interfaces of its own.

Extensions to other interfaces

Document.hasPrivateToken()

Returns a promise that fulfills with a boolean indicating whether the browser has a private state token stored from a particular issuer.

Document.hasRedemptionRecord()

Returns a promise that fulfills with a boolean indicating whether the browser has a redemption record originating from a particular issuer.

HTMLIFrameElement.privateToken

Mirrors the value of the<iframe>privateToken attribute.

fetch() /Request(), theprivateToken option

An object representing a private state token operation. Fetch calls with theprivateToken option specified initiate operations such as issuing or redeeming tokens.

XMLHttpRequest.setPrivateToken()

Adds private state token information to anXMLHttpRequest call, to initiate private state token operations.

HTML elements

<iframe>, theprivateToken attribute

Contains a string representation of an options object representing a private state token operation. IFrames containing this attribute can be used to initiate operations such as issuing or redeeming tokens.

HTTP headers

Permissions-Policy; theprivate-state-token-issuance directive

Controls usage oftoken-request operations.

Permissions-Policy; theprivate-state-token-redemption directive

Controls usage oftoken-redemption andsend-redemption-record operations.

Sec-Redemption-Record

A request header that forwards a redemption record to another party to convey trust when asend-redemption-record fetch request is made.

Sec-Private-State-Token

Exists both as a request and a response header, used during issuance and redemption requests to transmit request data (such as blinded nonces used to generate tokens) and response data (such as tokens and redemption records).

Sec-Private-State-Token-Crypto-Version

A request header sent to an issuer server that states which cryptographic protocol version should be used to sign blinded nonces when generating tokens.

Sec-Private-State-Token-Lifetime

A response header, sent by the redeemer server, to indicate to the browser how long it should cache a particular redemption record for.

Security considerations

Private state tokentoken-request operations are controlled by theprivate-state-token-issuancePermissions-Policy directive, whereastoken-redemption andsend-redemption-record operations are controlled by theprivate-state-token-redemption directive.

Specifically, where a defined policy blocks usage, any attempts to initiate private state token operations via fetch requests will fail.

Examples

See thePrivate State Token Demo Issuer for an example implementation.

Specifications

Browser compatibility