Skip to main content

Authentication

Every call to the Edge API carries up to two independent credentials. They answer two different questions and are checked independently.

Touchpoint credential — "which app is calling?"​

Two headers, present on every /api/v1/* call:

HeaderMeaning
X-Touchpoint-CodePublic identifier of your touchpoint.
X-Touchpoint-KeySecret paired with the code. Shown once at creation time — store it server-side.

A missing, wrong, or disabled credential returns 401 TOUCHPOINT_UNAUTHORIZED before anything else is evaluated. There is no separate "resolve my touchpoint" call — every operation validates the credential inline as part of doing its job.

Some endpoints — the ISO-3166 reference data — need only the touchpoint credential, no logged-in consumer, because the data is pre-auth (a registration form needs to show countries before an account exists).

Customer JWT — "which consumer is calling?"​

Returned by register, register/complete, login, and identify as a token field. Attach it as a bearer token on any customer-scoped call:

Authorization: Bearer <token>

Required on:

  • GET/PATCH /api/v1/me (self-service profile)
  • POST /api/v1/verifications/{channel}/request and /confirm
  • POST /api/v1/password/change
  • POST /api/v1/logout

A missing, invalid, or expired JWT returns 401 UNAUTHENTICATED — distinct from TOUCHPOINT_UNAUTHORIZED. Both the touchpoint credential and the Customer JWT are required together on these calls; the touchpoint credential is never optional.

The consumer's identity always comes from the JWT's sub claim — never from anything you put in the request body. Trying to act on another customer's data via a client-supplied id has no effect; the identity is always the token's own.

Why two credentials, not one​

The touchpoint credential lets Thalamus Lite apply per-app rate limits and (via API Gateway usage plans) throttling, regardless of whether anyone is logged in. The Customer JWT is short-lived and scoped to one consumer session. A single combined credential couldn't express "an app with no logged-in user yet" (registration, pre-auth reference data) as cleanly.

Password vs one-time-code touchpoints​

A touchpoint is configured (by the Business) with an authentication mode:

  • PASSWORD — register/register/complete bodies carry a password; login requires identifier + password.
  • One-time code — no password is stored. (One caveat today: OTP login itself is a reserved seam — see the Roadmap — so a one-time-code touchpoint can register consumers but they can't yet log back in a second time through this API.)

Your touchpoint's mode is fixed by configuration — you don't choose it per-request.