Tap sessions

A tap proves someone is holding a specific physical item. verify() records that tap and hands back a session scoped to it: every call the session makes carries the session credential, so the session token never has to be threaded through your own code.

Verify a tap

verify() takes the chip_id and e from the tap and returns the session:

import { EndstatePublicClient, publishableKey } from "@endstate-sdk/core";

const endstate = new EndstatePublicClient({
  publishableKey: publishableKey(process.env.NEXT_PUBLIC_ENDSTATE_KEY),
});

const session = await endstate.verify({ chip_id: chipId, e, c });

session.item; // the verified unit - no extra request
session.scope; // what this session authorizes
session.expiresAt; // when it stops working

It never takes a URL. To get a tap out of one, parse it first with tryParseTapUrl, which returns null rather than throwing:

import { tryParseTapUrl } from "@endstate-sdk/core";

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

const session = await endstate.verify(tap);

That handles both shapes a tap arrives in: an Endstate tap URL (/verify/{chip_id}?e= or /u/{chip_id}?e=), and a tap redirect destination on your own domain, where the values arrive as endstate_chip_id and endstate_e query parameters instead.

Keeping the parse separate is deliberate. “Is there a tap on this page?” is an offline question whose answer is often no - a direct visit, or a reload after the query was stripped - so it belongs in a branch rather than a try around a network call. See Host your own verify page for the full flow.

The e value is single-use. Never cache one and never replay one yourself. verify() derives its idempotency key from the tap, so a page refresh replays the original response instead of spending the credential and reporting a false “already scanned”.

Act on the session

The session exposes exactly what a tap authorizes:

Resource	Methods
`session.claims`	`create` · `get` · `waitUntilSettled`
`session.transfers`	`create` · `get` · `waitUntilSettled`
`session.sessionTokens`	`current` · `revoke`

Sessions cannot be refreshed

A new session needs a new tap. There is no refresh, by design - the session’s authority comes from someone having physically held the item.

session.isExpired(); // local clock check
session.msUntilExpiry(); // milliseconds remaining, or null
await session.revoke(); // end it early

isExpired() is a local clock check, for interface copy only. The SDK never gates a request on it: a device clock is not authoritative. The definitive answer is a 401 session_token.invalid_or_expired from the API.

Adopting a session you already hold

If your server issued the session, or you kept the token across a page reload, adopt it rather than re-verifying:

const session = endstate.session(token);

// Fill in expiry and scope, which a bare token does not carry.
await session.refreshScope();

Where the tap comes from

In a browser, core can capture the tap for you through a registered tap source, or take the output of @endstate-sdk/reader directly - see Browser. On a server, you already have chip_id and e from whatever forwarded them to you.

Get started

Core SDK

Reader SDK

Verify a tap

Act on the session

Sessions cannot be refreshed

Adopting a session you already hold

Where the tap comes from

​Verify a tap

​Act on the session

​Sessions cannot be refreshed

​Adopting a session you already hold

​Where the tap comes from

Verify a tap

Act on the session

Sessions cannot be refreshed

Adopting a session you already hold

Where the tap comes from