To implement email verification on your site, update your form markup to request
the token and add server-side validation for incoming tokens.

## Register for the origin trial

Verifying sites must have the origin trial configured on their site.

- [Register for the origin trial](https://developer.chrome.com/origintrials#/view_trial/10696049115004929)
- Serve the [origin trial token](https://developer.chrome.com/docs/web-platform/origin-trials)

As of Chrome 154 [third-party origin
trials](https://developer.chrome.com/docs/web-platform/third-party-origin-trials) are supported with an
important caveat: *the registered origin for the trial must be same-site to the
issuer*. For example:

- **Issuer domain** : `issuer.example`
- **OT registrant** : `https://issuer.example`
- **JavaScript origin** : `https://issuer.example` (or `https://app.issuer.example` with subdomain matching)

## Configure form fields

Add a hidden token field to your email submission form:

    <input
      type="email"
      name="email-address"
      autocomplete="email">
    <input
      type="hidden"
      name="token"
      autocomplete="email-verification-token"
      nonce="rAnD0m-VaLuE">

Field requirements:

- **Email field** : Set `type="email"` and `autocomplete="email"` so Chrome can autofill and recognize the address.
- **Token field attributes** :
  - Set `autocomplete="email-verification-token"`: Chrome identifies this field to populate the token on submission.
  - Set `nonce="<VALUE>"`: The site must provide a unique session-bound nonce to verify the form submission.

## Validate the email verification token (EVT)

When the user submits the form, your server receives the email address and the
token from the hidden field. An empty token field indicates that the browser or
provider does not support EVP, or the user skipped verification. If this occurs,
fall back to your existing verification process, such as sending an OTP or magic
link.

If a token is present, validate it as follows:

1. Parse the token using an SD-JWT library.
2. Validate expected values and session claims.
3. Verify DNS delegation.
4. Discover issuer metadata and fetch JWKS.
5. Verify cryptographic signatures and key binding.

### 1. Parse the token

The token uses the [RFC 9901: Selective Disclosure JWT
(SD-JWT+KB)](https://datatracker.ietf.org/doc/rfc9901/) format. Use the
appropriate libraries for your platform for parsing and validating the token.
For example, for Node you can use
[`@sd-jwt/core`](https://www.npmjs.com/package/@sd-jwt/core) and
[`jose`](https://www.npmjs.com/package/jose). In its raw form this looks like
this: an Issuer-signed JWT, followed by zero or more Disclosures, and ending
with a Key Binding JWT with each component separated by a tilde:

    <Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>

In the current implementation, the token contains zero disclosures
(`<Issuer-signed EVT>~<Key Binding JWT>`). However this might change in the
future.

Decode the token with the library:

    import { decodeSdJwtSync } from "@sd-jwt/core";
    import { createHash } from "node:crypto";
    const hasher = (data, alg) =>
      createHash(alg === "sha-256" ? "sha256" : alg)
        .update(data)
        .digest();
    const decoded = decodeSdJwtSync(rawToken, hasher);
    const evtPayload = decoded.jwt.payload;
    const kbPayload = decoded.kbJwt?.payload;

If `verifier.example` verifies `demo@provider.example`, the decoded token looks
similar to the following:

    {
      "evtJwtDecodedHeader": {
        "typ": "evt+jwt",
        "alg": "EdDSA",
        "kid": "issuer-key-id"
      },
      "evtJwtDecodedPayload": {
        "iss": "https://provider.example",
        "iat": 12345678901,
        "exp": 12345679901,
        "cnf": {
          "jwk": {
            "kty": "OKP",
            "crv": "Ed25519",
            "x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
          }
        },
        "email": "demo@provider.example",
        "email_verified": true
      },
      "kbJwtDecodedHeader": {
        "alg": "EdDSA",
        "typ": "kb+jwt"
      },
      "kbJwtDecodedPayload": {
        "aud": "https://verifier.example",
        "iat": 12345678901,
        "nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
        "sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
      },
      "disclosures": []
    }

### 2. Validate expected values and session claims

Check that the basic values in the payload match your provided and expected
values:

- `email_verified`: Must be `true`.
- `email`: Must match the email address submitted in the form.
- `aud` (audience): Must match your site's origin.
- `nonce`: Must match the nonce provided in your form.
- `iat` (issued at) and `exp` (expiry): Confirm the token is within its valid time window and has not expired.

> [!CAUTION]
> **Caution:** As of Chrome 156 (see [issue
> 549217427](https://issues.chromium.org/issues/549217427)) the email will be returned exactly as provided to the browser. Previously a case-insensitive comparison was necessary, as the provider may have returned a different format, for example `first.last@example.com` returns `First.Last@example.com`.

### 3. Verify DNS delegation

Verify the `_email-verification` DNS record for the email address domain. For
example, for `demo@gmail.com`, query the `_email-verification.gmail.com` TXT
record. For this provider, the query returns the location of the account
provider, that is `accounts.google.com`.

    $ dig +short TXT _email-verification.gmail.com
    "iss=accounts.google.com"

Verify that the issuer scheme is `https://` and that `https://<domain>` matches
the `iss` claim in the EVT.

### 4. Verify the EVT signature

Fetch the issuer's discovery metadata from
`https://<issuer>/.well-known/email-verification`:

    {
      "issuance_endpoint": "https://accounts.google.com/gsi/email-verification/issue",
      "jwks_uri": "https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks",
      "signing_alg_values_supported": ["EdDSA"]
    }

Fetch the JSON Web Key Set from `jwks_uri`.

Use your SD-JWT library to verify the token package. The library coordinates the
validation:

1. Validating the issuer signature on the EVT against the fetched JWKS.
2. Validating the browser's signature on the KB-JWT using the ephemeral public key in `cnf.jwk`.
3. Verifying the key binding (`aud`, `nonce`, and the digest hash `sd_hash`).

> [!CAUTION]
> **Caution:** The `kid` key ID field, if present, will identify the public key for verifying the signature. However if the `kid` is not returned (as is the case with Gmail) you will need to loop through each key to find the correct one.

Example verification logic in Node.js:

    import { SDJwtInstance } from "@sd-jwt/core";
    import { importJWK, compactVerify } from "jose";
    import { createHash } from "node:crypto";
    const hasher = (data, alg) =>
      createHash(alg === "sha-256" ? "sha256" : alg)
        .update(data)
        .digest();
    const sdJwt = new SDJwtInstance({ hasher });
    sdJwt.config({
      hasher,
      // Verifier for the Issuer-signed EVT
      verifier: async (data, sig) => {
        const token = `${data}.${sig}`;
        const header = decoded.jwt.header;
        const headerAlg = header.alg || "ES256";
        // Match by kid if present, or iterate across matching algorithm keys
        const keysToTry = header.kid
          ? jwksData.keys.filter(k => k.kid === header.kid)
          : jwksData.keys;
        for (const jwk of keysToTry) {
          try {
            const pubKey = await importJWK(jwk, jwk.alg || headerAlg);
            await compactVerify(token, pubKey);
            return true;
          } catch {
            // Try next candidate key
          }
        }
        return false;
      },
      // Verifier for the Key Binding JWT (KB-JWT)
      kbVerifier: async (data, sig) => {
        try {
          const browserJwkKey = evtPayload.cnf?.jwk;
          if (!browserJwkKey) return false;
          const pubKey = await importJWK(browserJwkKey, decoded.kbJwt.header.alg || "ES256");
          await compactVerify(`${data}.${sig}`, pubKey);
          return true;
        } catch {
          return false;
        }
      },
    });
    // The library automatically verifies EVT signature, KB-JWT signature, audience, nonce, and sd_hash
    const result = await sdJwt.verify(rawToken, {
      kb: {
        expectedNonce: sessionNonce,
        expectedAudience: "https://example.com",
        required: true,
      },
    });
    const verifiedPayload = result.payload;

If all steps succeed, you have verified the email address against the provider.
If verification fails, fall back to sending a confirmation email to the user
using your normal flow.

## Troubleshooting

If verification fails or the browser does not provide a token, check the
following common issues:

### Token field is empty on submission

- **Origin trial registration** : Confirm the `Origin-Trial` header or `<meta>` tag is served on the page. For third-party origin trials (Chrome 154+), the registered trial origin must be same-site to the issuer (`https://<issuer-domain>`). You can inspect the origin trial configuration on a site in DevTools under **Application** \> **Frames** \> (select the relevant frame) \> **Origin trials**.
- **Form markup** : Both `<input type="email" autocomplete="email">` and `<input type="hidden" autocomplete="email-verification-token" nonce="...">` must be in the same `<form>` element (not isolated across Shadow DOM boundaries), and `nonce` must not be empty.
- **Early submission or reused page**: The browser fetches the token in the background after the email is entered or autofilled. Submitting before the request completes leaves the token empty. This can happen if the user presses Return to submit the form after entering their email.
- **Browser and provider prerequisites** : The user must be signed in to a participating provider in the same browser profile and have **Verified
  Email** enabled in Chrome settings (`chrome://settings/contactInfo`).

### Issuer signature verification fails

- **Missing `kid` header** : The `kid` (Key ID) claim in the EVT header and JWKS is optional (for example, Gmail omits `kid`). If `kid` is absent, iterate through all candidate keys in the issuer's `jwks_uri` rather than failing on a key ID lookup.
- **Algorithm identifiers (EdDSA and Ed25519)** : Issuers and libraries may specify either `EdDSA` or `Ed25519` (alongside `ES256`). Ensure your JWK import and verification logic accepts both identifiers.
- **Issuer (`iss`) origin format** : The DNS TXT record (`_email-verification.<domain>`) contains a bare hostname (`iss=accounts.issuer.example`), whereas the EVT `iss` claim is a full HTTPS origin (`https://accounts.issuer.example`, with no trailing slash). Prefix `https://` to the DNS record value before comparing.

### Key binding (KB-JWT) validation fails

- **Mismatched or expired nonce** : Ensure the `nonce` rendered in the `<input>` matches the active session nonce on your server and has not been overwritten by another tab or consumed by a prior request.
- **Audience (`aud`) mismatch** : The `aud` claim is the verifier's HTTPS origin (`https://verifier.example`, with no path or trailing slash).

### Email claim (`email`) comparison fails

- **Casing and canonicalization** : Chrome 156+ returns the `email` claim byte-for-byte as entered in the form, but earlier browser versions or providers may return a canonicalized address (for example, `First.Last@example.com` for `first.last@example.com`). Use a case-insensitive comparison when matching the token's `email` claim against the submitted form value.