JavaScript Document hasPrivateToken() Method

What You’ll Learn

document.hasPrivateToken() is an instance method that asks whether the browser already stores a private state token from a given issuer (see MDN Document: hasPrivateToken()). Learn the Promise boolean result, issuer URLs, secure-context rules, exceptions, and safe feature detection.

Introduction

Private State Tokens help sites prove “this browser already completed a trust check with issuer X” without exposing a classic third-party cookie. Before requesting a new token, you can ask: do we already have one?

MDN: hasPrivateToken() returns a promise that fulfills with a boolean indicating whether the browser has a private state token stored from a particular issuer server.

Related tutorials: hasFocus(), getSelection(), hasRedemptionRecord().

Understanding document.hasPrivateToken()

An instance method on the Document interface from the Private State Token API (MDN). Call it on document, not as a free-floating global.

• issuer — string URL of an issuer server (MDN).
• Return value — a Promise that resolves to a boolean (MDN).
• true — a private state token from that issuer is stored.
• false — no stored token for that issuer (you may request one).
• Experimental — limited browser support; feature-detect first (MDN).
• Issuer limit — MDN: max two issuers per top-level origin; exceeding throws NotAllowedError.

📝 Syntax

General form of Document.hasPrivateToken (MDN):

hasPrivateToken(issuer)

Parameters

• issuer — a string representing the URL of an issuer server (MDN). Prefer a full absolute URL such as "https://issuer.example".

Return value

A Promise that resolves with a boolean value indicating whether the browser has a private state token stored from the specified issuer server (MDN).

Exceptions (MDN)

• InvalidStateError — the current Document is not yet active.
• NotAllowedError — not a secure context, or the maximum number of issuers per top-level origin (two) has been exceeded.
• TypeError — issuer is not a valid URL.

MDN-inspired sample (instance call)

const hasToken = await document.hasPrivateToken("https://issuer.example");
if (!hasToken) {
  await fetch(
    "https://issuer.example/.well-known/private-state-token/issuance",
    {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request",
      },
    },
  );
}

Tip: MDN’s snippet shows the same flow. This tutorial calls document.hasPrivateToken(...) because the method is an instance method on Document.

⚖️ hasPrivateToken vs everyday focus / cookies

Examples Gallery

Examples follow MDN Document: hasPrivateToken() with beginner-safe feature detection. Many demos will report “not supported” outside Chromium.

if (typeof document.hasPrivateToken === "function") {
  console.log("hasPrivateToken is available");
} else {
  console.log("hasPrivateToken is not supported in this browser");
}

hasPrivateToken is available
— or —
hasPrivateToken is not supported in this browser

async function checkIssuer(issuer) {
  if (typeof document.hasPrivateToken !== "function") {
    return "unsupported";
  }
  const hasToken = await document.hasPrivateToken(issuer);
  return hasToken ? "token present" : "no token yet";
}

checkIssuer("https://issuer.example").then(console.log);

unsupported
— or —
no token yet
— or —
token present

async function ensureToken(issuer) {
  if (typeof document.hasPrivateToken !== "function") {
    throw new Error("Private State Tokens not supported");
  }

  const hasToken = await document.hasPrivateToken(issuer);
  if (!hasToken) {
    await fetch(`${issuer}/.well-known/private-state-token/issuance`, {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request",
      },
    });
  }
  return hasToken;
}

Would check, then maybe POST token-request
(requires a real issuer + supporting browser)

async function safeHasToken(issuer) {
  if (typeof document.hasPrivateToken !== "function") {
    return { ok: false, reason: "unsupported" };
  }
  try {
    const hasToken = await document.hasPrivateToken(issuer);
    return { ok: true, hasToken };
  } catch (err) {
    // TypeError | NotAllowedError | InvalidStateError (MDN)
    return { ok: false, reason: err.name, message: err.message };
  }
}

safeHasToken("not-a-url").then(console.log);

{ ok: false, reason: "unsupported" }
— or —
{ ok: false, reason: "TypeError", message: "..." }

async function checkWhenSecure(issuer) {
  if (!window.isSecureContext) {
    return "Need HTTPS (or localhost) first";
  }
  if (typeof document.hasPrivateToken !== "function") {
    return "API missing";
  }
  return (await document.hasPrivateToken(issuer)) ? "yes" : "no";
}

checkWhenSecure("https://issuer.example").then(console.log);

API missing
— or —
yes / no
— or —
Need HTTPS (or localhost) first

🚀 Common Use Cases

• Skip redundant issuance — only request a token when MDN’s boolean is false.
• Privacy-preserving trust — Private State Tokens as a cookie alternative family (MDN API).
• Feature-gated UX — hide token flows when the method is unsupported.
• Secure-only demos — enforce HTTPS before calling the API.
• Issuer budgeting — stay within the two-issuer-per-origin limit (MDN).
• Learning / migration — understand experimental privacy APIs without relying on them yet in production.

📝 Notes

• MDN: marked Experimental — verify compatibility before production.
• MDN: returns a Promise that fulfills with a boolean.
• MDN: issuer must be a valid URL or you get TypeError.
• MDN: secure context required; otherwise NotAllowedError.
• MDN: at most two issuers per top-level origin.
• Related: hasFocus(), getSelection(), hasRedemptionRecord().

💡 Best Practices