Authentication

Every public API request authenticates with a ttk_ API key sent in the x-api-key header. There are no session cookies or OAuth flows on the public API — one header, one key, scoped to exactly what you grant it.

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.

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, logs
`servers:write`	Create / start / stop / restart / delete servers; set version, properties, MOTD, plan-adjacent settings, alert webhook, public status; 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 ABCD-1234

The approval must happen in an owner dashboard session — a ttk_ key cannot self-approve a device.

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

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