XMLHttpRequest: setPrivateToken() method

Syntax

js

setPrivateToken(privateToken)

Parameters

privateToken

An object containing options for initiating a private state token operation. Possible properties include:

issuers Optional

An array of strings containing the URLs of issuers that you want to forward redemption records for. This setting is ignored unless operation is set to send-redemption-record, in which case the issuers array must be included.

operation

A string representing the type of token operation you want to initiate. Possible values are:

token-request: Initiates a token request operation.
token-redemption: Initiates a token redemption operation.
send-redemption-record: Initiates a send redemption record operation.

refreshPolicy Optional

An enumerated value that specifies the expected behavior when a non-expired redemption record for the current user and site has previously been set. This setting is ignored unless operation is set to token-redemption. Possible values are:

none: The previously-set redemption record should be used, and a new one should not be issued. This is the default value.
refresh: A new redemption record is always issued.

version

A number indicating the version of the cryptographic protocol you wish to use when generating a token. Currently this is always set to 1, which is the only version that the specification supports. When specifying the privateToken option, this property is mandatory.

Return value

None (undefined).

Exceptions

InvalidStateError DOMException: Thrown if the associated XMLHttpRequest is not in an opened state, or send() has already been called on it.
NotAllowedError DOMException: Thrown if use of Private State Token API operations is specifically disallowed by a private-state-token-issuance or private-state-token-redemption Permissions Policy.
TypeError: Thrown if the operation is set to send-redemption-record, and the issues array was empty or not set, or one or more of the specified issuers are not trustworthy, HTTPS URLs.

Examples

Issuing a private token

js

const hasToken = await Document.hasPrivateToken(`issuer.example`);
if (!hasToken) {
  const request = new XMLHttpRequest();
  request.open(
    "POST",
    "https://issuer.example/.well-known/private-state-token/issuance",
  );
  request.setPrivateToken({
    version: 1,
    operation: "token-request",
  });
  req.send();
}

Redeeming a private token

js

const request = new XMLHttpRequest();
request.open(
  "POST",
  "https://issuer.example/.well-known/private-state-token/redemption",
);
request.setPrivateToken({
  version: 1,
  operation: "token-redemption",
  refreshPolicy: "none",
});
req.send();

Forwarding a redemption record

js

const hasRR = await Document.hasRedemptionRecord(`issuer.example`);
if (hasRR) {
  const request = new XMLHttpRequest();
  request.open("POST", "some-resource.example");
  request.setPrivateToken({
    version: 1,
    operation: "send-redemption-record",
    issuers: ["https://issuer.example"],
  });
  req.send();
}

Specifications

Specification
Private State Token API # dom-xmlhttprequest-setprivatetoken

Browser compatibility

	desktop					mobile
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on iOS	Samsung Internet	WebView Android	WebView on iOS
`setPrivateToken` Experimental	Chrome – Full support Chrome 117 (Release date: 2023-09-12) footnote Full support	Edge – Full support Edge 117 (Release date: 2023-09-15) footnote Full support	Firefox – No support Firefox footnote No support	Opera – Full support Opera 103 (Release date: 2023-10-03) footnote Full support	Safari – No support Safari footnote No support	Chrome Android – Full support Chrome Android 117 (Release date: 2023-09-12) footnote Full support	Firefox for Android – No support Firefox for Android footnote No support	Opera Android – Full support Opera Android 78 (Release date: 2023-10-23) footnote Full support	Safari on iOS – No support Safari on iOS footnote No support	Samsung Internet – Full support Samsung Internet 24 (Release date: 2024-01-25) footnote Full support	WebView Android – No support WebView Android footnote No support	WebView on iOS – No support WebView on iOS footnote No support

Tip: you can click/tap on a cell for more information.

Full support: Full support
No support: No support
: Experimental. Expect behavior to change in the future.

Legend