Authentication
Send your API key as a bearer token on every request:
curl $TMBILLING_URL/v1/me \
-H "Authorization: Bearer sk_live_…"
A key identifies one organization. Everything it reaches — businesses, customers, invoices — belongs to that organization, and tmbilling enforces the boundary in the database rather than in whichever query happens to run. You cannot read another organization's data by guessing an id.
Select a key mode
Every business has a live mode and a test mode, each with its own business id. You create each key for one of the two modes:
| Mode | Prefix | Reaches | Use it for |
|---|---|---|---|
test | sk_test_ | Test mode only | Development, CI, anything that must never charge a card |
live | sk_live_ | Live mode only | Production |
Point a test key at a live business id, or the reverse, and you get 404 No such business. That
refusal is what stops a staging deployment with the wrong key from billing your real customers.
Time Travel and configuration transfer cross the two modes, so they run from the dashboard, which
signs in with its own credential. An integration key gets 403 on them. See
Test and live mode.
Create and revoke keys
Create keys in the dashboard under Settings → Developer → API keys, or through the API:
/v1/api_keysPass livemode (test or live, default test), an optional name, and an optional scope
(write, the default, or read). A read key cannot change anything. tmbilling returns the
secret exactly once, when you create the key. GET /v1/api_keys lists your
keys with a non-secret fragment so you can identify them, and never returns a secret again. If you
lose a key, revoke it and create another.
/v1/api_keys/{id}/revokeRevocation takes effect immediately.
Check which organization a key resolves to
/v1/meUse this as a deployment smoke test. If it returns the wrong organization or the wrong mode, stop before anything else runs.
Recognise an authentication failure
| Status | Error | Cause |
|---|---|---|
401 | authentication_error | The key is missing, malformed or revoked. |
403 | permission_error | The key is valid but may not do this, for example a read key on a write. |
403 | permission_error, code live_access_required | Hosted only: our team turned live mode off for the organization. Test mode and reads still work. Contact us to turn live mode on. |
403 | permission_error, code account_restricted | Hosted only: the organization is read-only. Its plan is unpaid (pay the open invoice), or it stayed above its plan's limit and our team made it read-only (change to a plan that covers its billing). |
404 | invalid_request_error | The business id belongs to the other mode, or does not exist. |
See Errors.
Related
Spend limits and top-up
Keep AI usage spend in check: hard and soft spend limits per customer, subscription or user, limit tiers, alerts with a state per threshold, credit runway, automatic top-up, early usage invoices, a rate-change preview and a usage widget for your app.
Idempotency
Send an Idempotency-Key on every write so a retry after a timeout cannot charge twice, and learn what happens when you reuse a key with a different body.