Authentication

​

Overview

​

API key

• Accepted on most /v1/* endpoints. Some actions require a session token instead — for example, creating a claim or a transfer — and GET /v1/session-tokens/current accepts only a session token.
• Returned once at creation — if you lose it, you must obtain a new one.
• Issued by Endstate during onboarding.
• Rotation and revocation are handled by Endstate — there is no self-serve key-management endpoint. Contact Endstate to rotate a key or to revoke a compromised one; a replacement is issued and the old key is disabled.

​

Example request

curl https://api2.endstate.io/v1/units \
  -H "Authorization: Bearer end_sk_test_..."

{
  "units": [
    {
      "id": "8e1a7f50-90ab-4cde-f012-3456789abcde",
      "name": "Black Hoodie — Size M",
      "external_id": "sku-hoodie-black-m",
      "created_at": "2026-05-14T10:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

​

Session token

• Issued by POST /v1/chips/{chip_id} (chip verification).
• Default lifetime: 600 seconds. Configurable per-request via the ttl parameter (60–3600 seconds).
• Scoped to exactly one chip, one unit, and one organization.
• Returned once — opaque and unrecoverable after issuance.
• Required to authorize unit-scoped actions on behalf of the user who tapped — for example, creating a claim (POST /v1/units/{unit_id}/claims) or a transfer (POST /v1/units/{unit_id}/transfers).
• The only credential accepted by GET /v1/session-tokens/current, which lets a client confirm the scope of its session without ever seeing your API key.

​

Example request

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

{
  "chip_id": "ABCDEF0123",
  "unit_id": "8e1a7f50-90ab-4cde-f012-3456789abcde",
  "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expires_at": "2026-05-14T10:40:00.000Z"
}

​

Telling them apart

• end_sk_... — API key. Full organization access; server-only.
• end_sess_... — Session token. Single-chip scope; short-lived.

​

Authentication errors

​

Next steps