Host your own verify page

By default, tapping a chip lands the user on Endstate’s hosted verify page. This guide shows how to host that experience yourself - your domain, your design - by combining tap redirects with a verify call. You configure a redirect to a page you own, and Endstate sends each tap there with the chip_id and one-time e. Verifying that tap is a single call - POST /v1/taps - and it takes either credential:

	With a backend	Without a backend
Your page sends the tap to	your server	Endstate directly
Who calls `POST /v1/taps`	your server	the browser
Credential on the call	secret key (`end_sk_...`)	publishable key (`end_pk_live_...`)
You get back	the unit and a session token	the unit and a session token

One endpoint, one response shape, and the same result either way: a session token bound to that tap. Pick the backendless path if your verify page is static or you have no server to run.

Prerequisites

Registered items - a collection, a unit per item, and a paired chip. See Set up your catalog.
A secret API key (end_sk_...), used server-side only. Needed to configure redirects either way.
A page on your domain to receive taps (the redirect destination).
Backendless only: your publishable key from GET /v1/publishable-keys, and your page’s origin on your browser allow-list.

Point taps at your page

Set a redirect_url to the page you’ll host. Choose the level that matches how broadly it applies - a single unit, a whole collection, or your organization default:

await endstate.collections.update("8e1a7f50-90ab-4cde-b012-3456789abcde", {
  redirect_url: "https://brand.example/verify",
});

curl -X PATCH https://api2.endstate.io/v1/collections/8e1a7f50-90ab-4cde-b012-3456789abcde \
  -H "Authorization: Bearer end_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://brand.example/verify" }'

From now on, a tap on any item covered by that redirect sends the user to your URL with the tap’s chip_id and e appended:

https://brand.example/verify?endstate_e=C78566198547116F3A715DC1C62AF96F&endstate_chip_id=ABCDEF0123

The most specific redirect wins (unit → collection → org default). See Tap redirects for the full resolution order.

Read the tap on your page

Both paths start here - pull the two values off the query string.

// On https://brand.example/verify
const params = new URLSearchParams(window.location.search);
const chipId = params.get("endstate_chip_id"); // the API's chip_id
const e = params.get("endstate_e");

With @endstate-sdk/core, tryParseTapUrl does the reading for you and returns null when the page carries no tap - see Tap sessions.

const tap = tryParseTapUrl(window.location.href);
if (!tap) return renderTapPrompt();

The e value is single-use and short-lived. Verify promptly; do not log it or store it at rest.

Verify the tap

A successful verify is the proof of authenticity - it can only be produced by a genuine chip that was just tapped.

With a backend
Without a backend

Forward the two values to your server. Your browser code never calls Endstate with your secret key.

// On your page. This is a call to YOUR OWN endpoint, not to Endstate -
// plain fetch, no SDK involved.
const result = await fetch("/api/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ chipId, e }),
}).then((r) => r.json());

Your server verifies the tap. The unit comes back with the session, so you are done in one call.

// Your /api/verify handler - secret key stays here.
import { EndstateClient, secretKey } from "@endstate-sdk/core";
import { isEndstateApiError } from "@endstate-sdk/core/errors";

const endstate = new EndstateClient({
  apiKey: secretKey(process.env.ENDSTATE_SECRET_KEY),
});

try {
  const session = await endstate.verify({ chip_id: chipId, e });
  return { unit: session.item, token: session.token };
} catch (error) {
  // Branch on error.code: chip.invalid_e_value / chip.already_scanned → not
  // authentic (ask the user to tap again); chip.not_found → bad chip_id.
  if (isEndstateApiError(error)) throw new Error(error.code);
  throw error;
}

// Your /api/verify handler - secret key stays here.
const res = await fetch("https://api2.endstate.io/v1/taps", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ENDSTATE_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chip_id: chipId, e }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(error.code);
}

const { unit, session_token } = await res.json();

The page calls the same endpoint itself, using your publishable key. That key identifies your organization and authorizes nothing on its own - the authority is still the one-time e, which cannot be forged.

// On your page. end_pk_live_... is safe in page source.
import { EndstatePublicClient, publishableKey } from "@endstate-sdk/core";
import { isEndstateApiError } from "@endstate-sdk/core/errors";

const endstate = new EndstatePublicClient({
  publishableKey: publishableKey(PUBLISHABLE_KEY),
});

try {
  const session = await endstate.verify({ chip_id: chipId, e });
  session.item; // the verified unit
  session.token; // end_sess_..., for a follow-on claim
} catch (error) {
  // same codes as the server-side path
  if (isEndstateApiError(error)) throw new Error(error.code);
  throw error;
}

// On your page. end_pk_live_... is safe in page source.
const res = await fetch("https://api2.endstate.io/v1/taps", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${PUBLISHABLE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chip_id: chipId, e }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(error.code); // same codes as the server-side path
}

const { session_token, unit } = await res.json();

This is the same endpoint and the same response the server-side path gets, so the verified unit arrives with the token - no second call to render the authenticity view.One difference, deliberate: a publishable key may not send ttl or dry_run. The token gets the 600-second default; an untrusted browser does not choose how long its own credential lives.

Your page’s origin must be on your browser allow-list first. If it isn’t, the browser blocks the call before it reaches the API and you’ll see an opaque network error rather than a useful response.

See Verify a unit for the full response, the session-token model, and error handling.

Render the result

Render a branded authenticity view from the unit - its name, attributes, and serial (unit.collection.token.serial). With a backend, return the unit to your page and pass the session_token.token (end_sess_...) along if a follow-on action needs it; it’s safe in the browser, unlike your API key. Backendless, the page already holds both.A successful verify means authentic. A failure (chip.invalid_e_value, chip.already_scanned) means the tap couldn’t be confirmed - show a “tap again” state rather than asserting the item is fake on a single failed tap.

The session token also authorizes claiming the unit - transferring ownership to a recipient. You can add that to your page as a next step. See Claim a unit.

Next steps

Verify a unit

The full server-side verification flow and its response in depth.

CORS origins

Allow-listing the origins your page is served from, required for the backendless path.

Tap redirects

Resolution order and how to set redirects per unit, collection, or org.

Get started

Pairing

Verification

Ownership

Host your own verify page

Prerequisites

Next steps

Verify a unit

CORS origins

Tap redirects

​Prerequisites

​Next steps

Verify a unit

CORS origins

Tap redirects

Prerequisites

Next steps