Not available yet. The authentication layer is built; the
/api/v1/routes are not. This page describes the intended behaviour.
Every request carries a bearer token.
Authorization: Bearer ts_live_a1b2c3d4e5f6...curl "https://truestat.io/api/v1/sites" \
-H "Authorization: Bearer $TRUESTAT_API_KEY"That is the whole of it. No signing, no timestamps, no nonces.
Get a key
HTTPS is required
Requests over plain HTTP are refused. A key sent unencrypted is a key that has been disclosed.
What a key can reach
A key is bound to your organisation and, optionally, to specific sites.
Organisation is the outer boundary. A key cannot read another organisation's data under any circumstances, including a site id belonging to one.
Sites narrow it further. A key with no sites named reads every site in your organisation, including ones added later.
Every request resolves what the caller may read before any query runs. Passing a site id you do not have access to returns the same response as passing one that does not exist — see Errors.
Everything is read-only
There is no write scope, no admin scope and no way to widen a key. This is structural: the code path that resolves an API key's access hardcodes read access, so a future endpoint cannot accidentally accept a key for a write.
A leaked key means your analytics are readable. It does not mean anything can be changed, deleted or reconfigured.
Expiry and revocation
A key stops working the moment it is revoked, and on its expiry date if it has
one. Both produce 401 with invalid_credential — the same response as a
garbage token, deliberately, so a caller learns "this credential does not work"
rather than "this credential existed and was revoked at 14:02".
Last used
Every successful authentication updates the key's last-used timestamp, visible in the key list. It is what tells you whether a key is still part of something before you revoke it.
Recording it never blocks or slows your request.
Two other ways in — not for the API
The API takes an API key. For completeness, two other credentials exist in the
product and neither is for /api/v1/:
Your dashboard session. The app's own requests use your signed-in session. That is not something to script against.
A share link. A read-only, anonymous view of one dashboard. See Public dashboards. It is a web page, not an API surface.
Keeping the key out of the wrong places
Server-side only. A key in browser JavaScript is public.
Environment variables, not source. A key in a repository is in every clone and in your git history permanently.
The
ts_live_prefix is designed to be greppable, so secret scanners can catch a key before it is pushed.
Testing your key
curl -i "https://truestat.io/api/v1/sites" \
-H "Authorization: Bearer $TRUESTAT_API_KEY"200 with a list of sites means the key works and tells you the site ids every
other endpoint needs.
401 means the key is wrong, revoked or expired. 403 means the key is valid
but your plan does not include API access — check that you are on Pro.
See Errors.