Session tokens

A session token (end_sess_...) is issued automatically when a tap is verified. It records that a specific chip was physically tapped moments ago. It is not proof of ownership - it is proof of a recent tap.

What a session token represents

When a tap is recorded with POST /v1/taps, the API:

Validates the one-time credential (e value).
Records the tap against the chip’s scan count.
Returns a session_token object bound to that chip, the unit it is paired to, and your organization.

The token carries no identity claim beyond that tap event. If you need to authorize a unit-scoped action on behalf of a user (for example, confirming they are holding the physical product), pass the session token to that action instead of your API key.

Never expose your API key (end_sk_...) to a browser or mobile client. A session token is the credential a client should hold - either handed to it after server-side verification, or obtained by the client itself with your publishable key.

How a session token is issued

One endpoint issues session tokens: POST /v1/taps. Send the chip_id and the one-time e value from the tap, and the response includes the verified unit alongside:

string

The opaque end_sess_... credential. Returned once; never recoverable.

string

ISO-8601 timestamp when the token expires.

It accepts either credential, so where you call it from is your choice:

From your server, authenticate with your API key (end_sk_...).
From the browser, authenticate with your publishable key (end_pk_...). Use this when you host a verify page but have no backend to put behind it - the page records the tap itself and gets the same response.

Default lifetime: 600 seconds. An API-key request may send ttl (integer, 60-3600) in the body to change it, and the response expires_at reflects the actual expiry. A publishable-key request always uses the default - an untrusted client does not choose how long its own credential lives. The token is returned exactly once. If you lose it, you need another tap to get a new one.

Security properties

Opaque. The token carries no decodable payload. Its meaning is defined entirely by the introspection response.
Single-issue. Returned once in the tap response. Not logged or retrievable after that.
Short-lived. Expired tokens are rejected immediately. The default 600-second window is enough for a user interaction; request a shorter ttl for higher-sensitivity flows.
Client-safe. Unlike your API key, a session token is scoped to one chip and one unit. Passing it to a browser client exposes nothing beyond the current tap event.

Introspecting a session token

Use GET /v1/session-tokens/current to confirm what a session token is bound to. Authenticate the request with the session token itself - not your API key.

await session.sessionTokens.current();

curl https://api2.endstate.io/v1/session-tokens/current \
  -H "Authorization: Bearer end_sess_..."

Trimmed response (the same shape as the tap response’s session_token, minus token):

Response

{
  "expires_at": "2026-05-14T10:40:00.000Z",
  "scope": {
    "chip_id": "ABCDEF0123",
    "unit_id": "8e1a7f50-90ab-4cde-f012-3456789abcde",
    "organization_id": "3b2c1d0e-1234-5678-abcd-ef0123456789"
  }
}

string

ISO-8601 timestamp after which the token is no longer valid.

string

The 10-character hex identifier of the chip that was tapped.

string

The UUID of the unit the chip is paired to.

string

The UUID of your organization. Confirms the token belongs to your account.

A client can call this endpoint to confirm tap scope - which chip, which unit, which organization - without holding your API key.

Revoking a session token

Use DELETE /v1/session-tokens/current to end a session early instead of waiting for the token’s expiry - for example when the user completes or abandons the flow. Authenticate with the session token itself.

await session.revoke();

curl -X DELETE https://api2.endstate.io/v1/session-tokens/current \
  -H "Authorization: Bearer end_sess_..."

A successful revocation returns 204 No Content. The token is invalid immediately: subsequent requests with it - including a second DELETE - are rejected with session_token.invalid_or_expired. A new token requires a new tap. The full lifecycle: issue (returned once by POST /v1/taps) → introspect (GET /v1/session-tokens/current) → revoke (DELETE /v1/session-tokens/current) or expiry.

Calling the API directly from a browser requires your web origin to be on your organization’s allow-list - manage it with GET and PUT /v1/settings/cors-origins. See CORS origins for the entry formats and the request settings the API expects. Server-side calls are unaffected.

Use cases

Session tokens are most useful when you need to prove that a user physically tapped a product before allowing a unit-scoped action:

Gating digital content or experiences. After verification, pass the session token to your own backend or a client to unlock content tied to that unit.
Logging user interactions. Your server receives the tap event from the tap response; the session token lets a client confirm the same tap without a second server call.
Handoff to a client flow. Record the tap server-side, then pass end_sess_... to the client. The client can fetch the unit and introspect the token without access to your API key.

A chip-tap session token can read the unit it was issued for - GET /v1/units/{unit_id} accepts it in place of an API key - and authorizes the unit’s ownership actions: claiming it - handing it to its first owner - via the Claims API, and transferring it between owners via the Transfers API. A session token cannot read any other unit.

Errors

Code	HTTP	When
`session_token.invalid_or_expired`	401	Token is unknown, has expired, or was revoked.
`session_token.wrong_chip`	403	Token is valid but bound to a different chip than the one in the request.

Branch on error.code, not on HTTP status or message. See Error conventions for the full error envelope and handling guidance.

Endpoints

Method	Path	Auth	Description
`POST`	`/v1/taps`	API key or publishable key	Record a tap; returns a session token.
`GET`	`/v1/session-tokens/current`	Session token	Introspect the bearer session token.
`DELETE`	`/v1/session-tokens/current`	Session token	Revoke the bearer session token.
`GET`	`/v1/units/{unit_id}`	API key or session token	Fetch a unit. A session token reads only the unit it was issued for.

Full request and response schemas are in the API reference.

Next steps

Chips & verification

Learn how chips are paired to units and how taps produce the one-time credential used in verification.

Verify a unit

Step-by-step guide to running a complete verification flow and handling the session token.

Get started

Settings

Core concepts

API conventions

Updates

What a session token represents

How a session token is issued

Security properties

Introspecting a session token

Revoking a session token

Use cases

Errors

Endpoints

Next steps

Chips & verification

Verify a unit

​What a session token represents

​How a session token is issued

​Security properties

​Introspecting a session token

​Revoking a session token

​Use cases

​Errors

​Endpoints

​Next steps

Chips & verification

Verify a unit

What a session token represents

How a session token is issued

Security properties

Introspecting a session token

Revoking a session token

Use cases

Errors

Endpoints

Next steps