Authentication

TrueTick has two kinds of credential, for two different callers:

API keys (ttk_) — for scripts, CI, and integrations you run against your own account. One header, one key, scoped to exactly what you grant it. This page covers these.
App tokens (tta_) — for third-party apps other people run against their accounts (launchers, bots, companion apps). Minted through a device-authorization flow rather than created by hand, and narrower in reach than a key. See Sign in with TrueTick.

Every public API request authenticates with one or the other — an API key in the x-api-key header, or an app token in the Authorization: Bearer header — except the handful of /v1/public/* endpoints (signup, login, and the device-authorization endpoints that mint these credentials in the first place), which are deliberately unauthenticated: you need one of them to get a credential at all. There are no session cookies on the public API.

curl -H "x-api-key: ttk_your_key_here" https://api.truetick.gg/v1/whoami

⚠️

A ttk_ key is bound to a single account and is never the panel's god-key. It can only reach the per-account endpoints listed in the API Reference, and only within the scopes you granted it.

Creating and revoking keys

Keys are managed in the dashboard at Dashboard → API keys (opens in a new tab):

Create key — give it a name and check the scopes it needs.
Copy the ttk_… secret. It's shown once; store it in your secret manager or env.
Revoke any key from the same screen — it stops working immediately.

You can hold up to 25 active keys per account. Treat each key as a credential: scope it minimally, use separate keys per integration, and revoke on rotation.

Keys the CLI mints are named cli@signup, cli@login and cli@device. When the account is at 25 active keys, a password login or a device approval makes room by revoking the cli@… key that has gone unused the longest (a key never used counts from its creation), and a key you named cli@… in the dashboard counts as one of them. So give a key that CI or a script depends on a name without that prefix. If revoking cli@… keys can't bring the account under the cap, because your other keys fill it, the login is refused instead with api key limit reached (max 25 per account); revoke an unused key first. Create key in the dashboard never revokes anything: at the cap it's refused until you revoke a key.

The scope catalog

A key carries a fixed set of coarse scopes. The API checks the required scope on every call and returns 403 (PermissionDenied) if the key lacks it. The full catalog:

Scope	Grants
`servers:read`	List/inspect servers, read live metrics, capacity, regions, templates, versions, mods list, players, schedules, worlds, audit, account limits, resize quote, logs
`servers:write`	Create / start / stop / restart / delete servers; set version, properties, MOTD, plan-adjacent settings, alert webhook, public status; resize RAM; manage mods, ports, worlds, schedules, players (whitelist/op/ban/kick); manage databases & SFTP enablement
`console`	Run RCON commands (`…:command`)
`files:read`	List and read files in the server's jailed data volume
`files:write`	Write/delete/rename/copy/mkdir files; enable/rotate/disable SFTP
`backups`	Create, list, restore, delete backups
`billing:read`	Read wallet balance and ledger; create a Paddle checkout link

Anti-escalation by design. Credential-yielding operations are gated on a write scope even though they look like reads: enabling SFTP needs files:write, and fetching a database password needs servers:write. A read-only key can never mint a way to write.

Some endpoints are reachable by any valid key with no specific scope — notably GET /v1/whoami, which tells you which account the key is bound to.

What keys can't do

API keys are deliberately barred from account-level and destructive-billing surfaces: signup/login, password changes, top-ups and promo redemption, key management itself, member/invite management, Discord linking, and all admin RPCs. Those stay on the authenticated dashboard session. (This is enforced server-side, not just hidden — see the API Reference for the exact public surface.)

Using the key

Send the header on every request:

curl -H "x-api-key: ttk_your_key_here" \
  "https://api.truetick.gg/v1/servers?account_id=$ACCOUNT_ID"

CLI login flows

The truetick CLI offers three ways to authenticate, depending on whether you already have a key:

Device flow (recommended)

Run truetick login with no arguments. It opens a browser to a verification URL, you approve the device with the shown code, and the CLI receives and saves a fresh key:

truetick login
# Visit https://truetick.gg/device and enter the code shown (e.g. WDJB-MJHT)

The approval must happen in an owner dashboard session — a ttk_ key cannot self-approve a device. At the 25-key cap, approving revokes a cli@… key first (see Creating and revoking keys).

Password login

Mint a key non-interactively from email + password (handy in scripts you trust):

truetick login --email you@example.com --password   # prompts if value omitted

The key is minted only for an account you own: your own account while you're still its owner, otherwise the first account you own. If you own none, the login is refused with you are not an owner of any account; CLI keys are issued only to account owners. At the 25-key cap it revokes a cli@… key first (see Creating and revoking keys).

Paste a key

If you already created a key in the dashboard, paste it directly:

truetick login --key ttk_your_key_here

truetick signup --email you@example.com creates a new account and saves a key in one step. truetick logout removes the saved credentials.

Rate limits

The public API is rate-limited per key at 120 requests/minute (token bucket, burst 120). Exceeding it returns 429 (Too Many Requests) — back off and retry. See Errors for handling guidance.

Live log streams have their own concurrency caps (3 concurrent streams per key, 10 per account); see Stream logs.

Quickstart Servers