Skip to main content

Authentication

The credential​

A Tokenflow API key is a string prefixed tf_live_, sent in the x-api-key header on every request:

x-api-key: tf_live_9f2c…

The key is shown once, at creation. Only a SHA-256 hash of it is stored, so a lost key cannot be recovered — it is revoked and replaced.

What a key can read​

A key is bound to the identity that created it, and optionally to a protocol (a tenant):

KeyReads
Protocol key — issued by a protocol adminEverything that protocol owns, plus public data from any other protocol
Public key — issued by any verified accountPublic data only, aggregate resources only, with work-product fields removed

"Public" is the protocol owner's decision, made in the Tokenflow dashboard. A protocol that has not enabled public exploration is invisible here: requests for it answer PROTOCOL_NOT_PUBLIC.

Two rules follow from that, and they are worth stating plainly because they are the ones that surprise people:

  • Wallet-scoped resources are never readable across protocols. A key asking for another protocol's wallets gets 403 WALLET_SCOPE_UNAVAILABLE, whether or not that protocol is public.
  • Internal names and labels (name, primary_label, secondary_labels) are the protocol team's work product. They are stripped from every cross-protocol response, even a public one.

Issuing a key​

Keys are created on the Developers page of the Tokenflow dashboard, by the account that will own them. There is no API for creating your first key, and that is deliberate: the credential that authorises creating a key cannot be a key.

Whether an account may issue one without belonging to a protocol depends on the environment. If the button refuses, the answer comes back as 403 PUBLIC_ACCESS_DISABLED with an explanation — one place enforces the rule, so what the screen shows and what the API does cannot disagree.

Expiry and revocation​

Every key carries an expiry. An expired key answers 401 EXPIRED_API_KEY, a distinct code from INVALID_API_KEY so a client can tell "rotate me" from "this was never valid".

Revoking a key takes effect immediately. Revoking a key that is not yours answers 404 NOT_FOUND rather than 403 — otherwise the endpoint would be a way to find out which key IDs exist.

info

Enforced today on /v1/me. As each data resource ships it arrives already behind this check — no route is added first and secured later.