Authentication

Every request to the TrueTone API carries a bearer key:


GET /api/v1/health HTTP/1.1
Host: hub.truetone.ai
Authorization: Bearer ttk_your_key_here

Keys start with the ttk_ prefix. The header is read case-insensitively, and the token must be the whole credential: prefix included, nothing else appended.

The TrueTone Connector does not use keys at all. You sign in with your TrueTone account through OAuth when you connect it, and there is never a key to paste. See The TrueTone Connector.

Minting a key

Open the dashboard

Keys are created at hub.truetone.ai/account/api-keys . Give the key a name you will recognize later; names can be up to 80 characters.

Choose its Capability Groups

A key is scoped at issuance to a subset of your account’s Capability Groups. A key can never do more than the groups it was issued with, and it can never do more than your account role allows. Mint narrow keys for narrow jobs.

Copy the secret once

The full secret is shown exactly once, at creation. TrueTone stores only a hash of it plus the first few characters for display, so a lost secret cannot be recovered, only replaced.

Verifying a key

GET /api/v1/health is the cheapest authenticated call. It confirms the key works and echoes its id and its Capability Groups:


{
  "ok": true,
  "keyId": "9f8c1e2a-0000-4000-8000-000000000000",
  "scopes": ["read", "voice"]
}

Rotation

Rotating a key mints a replacement and gives the outgoing key a 24 hour grace window. During the grace window both keys work, so you can roll the new secret through your deployments without downtime. When the window closes, the old key answers the same 401 as a revoked one.

When authentication fails

Every credential problem gets one answer:


{ "error": "Invalid API key" }

A missing header, a malformed token, an unknown key, a revoked key, and an expired key are deliberately indistinguishable, so a probe learns nothing about which part was wrong. The full refusal contract is on the Errors page.

⚠️

Identity comes only from the key. Headers such as x-user-id are ignored, and no request field can widen what a key was issued to do.

Handling keys well

Keep secrets in your secret manager, never in source control or client-side code.
Mint one key per integration so revoking one job does not break another.
Prefer keys with only the Read access group for dashboards and reporting; save the groups that write for the jobs that need them.
Rotate on a schedule, and immediately if a secret may have leaked. The grace window makes routine rotation painless.