Skip to main content
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 your server verifies a tap with POST /v1/chips/{chip_id}, the API:
  1. Validates the one-time credential (e value).
  2. Records the tap against the chip’s scan count.
  3. 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. Session tokens are designed to be the credential you hand to a client after server-side verification.

​
How a session token is issued

Call POST /v1/chips/{chip_id} with the e value from the tap. The response includes: Default lifetime: 600 seconds. To request a different lifetime, pass ttl (integer, 60–3600) in the verify request body. The response expires_at reflects the actual expiry. The token is returned exactly once in the verify response. If you lose it, you must re-verify (perform another tap) to get a new token.

​
Security properties

  • Opaque. The token carries no decodable payload. Its meaning is defined entirely by the introspection response.
  • Single-issue. Returned once in the verify 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.
Trimmed response:
​
chip_id
string
The 10-character hex identifier of the chip that was tapped.
​
unit_id
string
The UUID of the unit the chip is paired to.
​
organization_id
string
The UUID of your organization. Confirms the token belongs to your account.
​
expires_at
string
ISO-8601 timestamp after which the token is no longer valid.
A client can call this endpoint to confirm tap scope — which chip, which unit, which organization — without holding your API key.
Calling the API directly from a browser requires your web origin to be on your organization’s CORS allowlist — requests from unlisted origins are blocked by the browser before they reach the endpoint. Ask Endstate to allowlist your origins during onboarding. 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 verify response; the session token lets a client confirm the same tap without a second server call.
  • Handoff to a client flow. Verify server-side, then pass end_sess_... to the client. The client can introspect to display unit details without access to your API key.
A chip-tap session token 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.

​
Errors

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

​
Endpoints

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.