Every Telm API request is authenticated with an API key that starts with tk_live_ — never with your dashboard login. Create a key in your account, send it in the Authorization header as a Bearer token, and it acts on behalf of your account on the groups where you are an admin. If a key leaks, revoke it in the dashboard and issue a new one.
1How API keys work
The Telm REST API does not use your browser session. Instead, each request carries an API key — a long secret string that starts with the prefix tk_live_ followed by random characters. The key identifies your account and authorises the call.
You generate keys from your account and can hold several at once (for example, one per script or service). The full secret is shown only once, at creation time; afterwards the dashboard lists a key by its short prefix (tk_live_ plus the first characters) so you can recognise it, and the full value is never kept after that.
- A key looks like tk_live_ followed by a long random string.
- Keys are created and managed in your dashboard.
- The full secret is displayed only once — copy it immediately and store it somewhere safe.
- Treat a key like a password: anyone who has it can call the API as you.
2Sending the key with every request
Pass the key in the Authorization header using the Bearer scheme. The header value is the word Bearer, a space, and then your key — for example, Authorization: Bearer tk_live_your_key_here.
For clients that cannot set an Authorization header conveniently, the API also accepts the key in an X-API-Key header. If both are present, the Authorization header wins. Requests over anything other than HTTPS are not accepted in production.
- Preferred: send Authorization: Bearer tk_live_...
- Alternative: send the key in the X-API-Key header instead.
- The base URL for every call is api.telm.com/api/public/v1.
- See the full endpoint list and schemas on the developers page.
3What a key can access
A key acts strictly on behalf of your account. It can only read or change groups where your account is an admin — a request that targets any other group returns 404, so the API never reveals that a group you cannot manage even exists.
Access also depends on the plan of the target group. The spam-check endpoint is open to every plan within the daily quota, while the full API (rules, settings, whitelist, journal, analytics, batch checks and webhooks) is available on the Pro plan or higher on the group involved.
- A key can touch only groups where you are an admin.
- Requests to groups you do not manage return 404, not 403.
- The daily quota is shared across all of your keys, counted per account.
4Revoking and rotating keys
If a key is exposed — committed to a repository, pasted into a chat, or leaked any other way — revoke it immediately from your dashboard. Revocation takes effect right away: the revoked key stops working right away — its cache entry is invalidated on revoke.
Because the daily quota is shared per account, revoking one key does not reset your usage counter. Rotating keys regularly is good hygiene: create the new key, deploy it to your service, confirm it works, then revoke the old one so there is no downtime.
- Revoke a key from your dashboard; it stops working almost immediately.
- Create the replacement first, roll it out, then revoke the old key for zero-downtime rotation.
- Revoking a key does not reset your daily quota — that resets at midnight UTC.
5Authentication errors
A missing, malformed, or revoked key returns 401 with a machine-readable error code and a human-readable message. If your requests suddenly start failing with 401, check that the key was not revoked and that the Authorization header is spelled exactly as Bearer plus a space plus the key.
A valid key that targets a group you do not manage returns 404. A valid key on a plan below Pro that calls a Pro-only endpoint returns 403 with a plan_required code and an upgrade hint.
- 401 — the key is missing, malformed, or revoked.
- 404 — the target group does not exist or you are not its admin.
- 403 plan_required — the endpoint needs Pro or higher on that group.