Getting started
Base URL
https://api.tokenflow.tech
Every path below is relative to it. The API is versioned in the path: everything under /v1/ is the first stable contract. /health sits outside the version on purpose — it describes the deployment, not the API.
Your first call
No credential needed to check that the API is reachable:
curl -s https://api.tokenflow.tech/health
{ "service": "external_api", "status": "ok" }
Everything that returns data needs a key. Once you have one, the call to make first is the one that tells you what that key is:
curl -s https://api.tokenflow.tech/v1/me \
-H "x-api-key: tf_live_…"
{
"key": {
"id": "9f2c81e4-…",
"prefix": "tf_live_9f2c",
"scopes": ["read"],
"rate_limit_tier": "standard",
"expires_at": "2027-09-22T00:00:00Z"
},
"access": {
"kind": "protocol",
"protocol": { "id": "3b1a…", "slug": "acme", "name": "Acme Protocol" }
}
}
Two things worth wiring into your client from day one: expires_at, so you rotate before a 401 rather than after, and access.kind, which tells you whether this key reads one protocol's data or only public data.
Import the spec
The service publishes its own OpenAPI 3.1 document, generated from the router — not written by hand, so it cannot drift from the code:
curl -s https://api.tokenflow.tech/v1/openapi.json
In Postman: Import → Link, paste that URL. The document's servers entry is the gateway of the environment you fetched it from, so a collection imported from dev calls dev.
Authentication
Requests carry the key in an x-api-key header:
curl -s https://api.tokenflow.tech/v1/protocols \
-H "x-api-key: tf_live_…"
Keys are issued in the Tokenflow dashboard, at app.tokenflow.tech/developers. A request without one is refused with 401.
See Authentication for how keys are issued, scoped and revoked.
Calling from a browser
A key works from any server, and from no browser origin at all until you say otherwise. That default exists because a key is a bearer credential: a permissive origin would let any page your users happen to visit spend your quota.
Origins are yours to manage. Every key carries its own allowlist, edited next to the key on the Developers page — no ticket, no waiting on us. Add the origin your web app is served from and requests from it start working within seconds.
Two consequences worth knowing before you debug something at 2am:
- The allowlist belongs to the key, not to the account. A key scoped to your staging site does not authorise your production site, which is what makes a leaked staging key useless elsewhere.
- An origin is matched exactly — scheme, host and port.
https://app.example.comandhttps://www.app.example.comare different origins, and so is the same host onhttp.