Credentials

​

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

await endstate.units.list();

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

{
  "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 one endpoint, POST /v1/taps, which takes either credential: your API key when your server verifies the tap, or your publishable key when your page verifies it directly.
• Default lifetime: 600 seconds. An API-key caller can send a ttl (60 to 3600 seconds) to change it; a publishable-key caller always gets the default.
• 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

await session.sessionTokens.current();

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

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

​

Publishable key

• Accepted by exactly one endpoint: POST /v1/taps, which exchanges a tap for a session token without involving your server. That endpoint also takes an API key, so the same call works from your server.
• Grants nothing on its own. It names your organization; it does not read, write, or authorize anything. The authority in that exchange is the one-time e value from the tap, which is unforgeable and works exactly once.
• Retrieve yours with GET /v1/publishable-keys, which itself requires your API key. See Publishable keys.
• Browser requests are matched against your organization’s allowed origins. A request with no Origin header is not origin-checked, so the allow-list governs where the key may be embedded, not who may call the API - the one-time e value remains the authority. See CORS origins.

​

Example request

const session = await endstate.verify({
  chip_id: "ABCDEF0123",
  e: "C78566198547116F3A715DC1C62AF96F",
});

curl -X POST https://api2.endstate.io/v1/taps \
  -H "Authorization: Bearer end_pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"chip_id": "ABCDEF0123", "e": "C78566198547116F3A715DC1C62AF96F"}'

{
  "id": "5c2f1b90-3d4e-4a5b-8c6d-7e8f90123456",
  "session_token": {
    "token": "end_sess_...",
    "expires_at": "2026-05-14T10:40:00.000Z",
    "scope": {
      "chip_id": "ABCDEF0123",
      "unit_id": "8e1a7f50-90ab-4cde-f012-3456789abcde",
      "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  },
  "chip": {
    "chip_id": "ABCDEF0123",
    "scan_count": 47
  },
  "unit": {
    "id": "8e1a7f50-90ab-4cde-f012-3456789abcde",
    "name": "Black Hoodie - Size M",
    "external_id": "sku-hoodie-black-m",
    "attributes": { "color": "black", "size": "M" },
    "collection": {
      "id": "2b7c9d10-4e5f-4a6b-8c7d-9e0f12345678",
      "name": "Black Hoodie - Fall 2026",
      "external_id": "hoodie-black-fall-2026",
      "contract": {
        "address": "0x1111111111111111111111111111111111111111",
        "chain_id": 84532,
        "status": "active"
      },
      "token": {
        "status": "active",
        "serial": 12
      }
    }
  },
  "redirect_url": "https://verify.brand.example/ABCDEF0123",
  "dry_run": false
}

​

Telling them apart

• end_sk_... - API key. Full organization access; server-only.
• end_sess_... - Session token. Single-chip scope; short-lived.
• end_pk_live_... - Publishable key. Identifies your organization; grants no access by itself, so it is safe in page source. Accepted only by POST /v1/taps - sending one anywhere else returns 401.

​

Authentication errors

​

Next steps