Authentication and tokens

Create a read-only API token, send it as a Bearer header, and understand the role, plan and scope checks behind every request.

Start hereUpdated

Create a token

Settings, Integrations, API tokens in the dashboard. Give it a label, choose an expiry (30, 90 or 365 days, or never) and create it. Tick Also allow the read-only REST API to give it the api:read scope; without it the token carries only mcp:read and works on the MCP endpoint alone. A token looks like ssk_ followed by 43 characters, is shown once, and is stored only as a SHA-256 hash. Up to 10 active tokens per person per organisation.

Send it

bash
curl -H "Authorization: Bearer ssk_..." https://serverstats.cc/api/v1/orgs/ORG_ID/servers

Send the token only in the Authorization header, never in a URL. A cookie sent along with a token is ignored: a token never borrows a browser session's wider reach.

What a token is

  • One person, one organisation. A token acts as its owner, with their current role and permissions. A staff member's token sees server health only. Roles can change what a role may read, and a change applies to tokens at once (403 forbidden).
  • Read-only. Any method other than GET and HEAD answers 405 read_only.
  • Network only. The check runs on every request, so a downgrade takes effect at once (403 plan_required).
  • Revoked at once when you revoke it, when it expires, when its owner leaves or is removed, or when the organisation is deleted.
  • Limited to an allow-list. A token reaches only the routes listed in this reference, for its own organisation. Members, invites, the audit log, billing, tokens, alert and Discord configuration, store secrets, claim codes, notes and every write return 404 not_found, as if the route did not exist.
  • Pseudonymous data. Players are 64-character hex pid values. Names appear only if the organisation shows names and the role may see them. No IP addresses, chat or emails are ever returned, and stored punishment reasons are never available to tokens.

Plan and history

Token routes are limited to your plan's history window (24 hours, 90 days or 2 years). A range beyond it is clamped, and the response says so in history_limit. Some routes need extra plan features even on Network; they answer 403 plan_required with details.feature.

Org and server ids

Both are UUIDs. Your organisation id is in the URL the dashboard shows when it creates a token. GET /orgs/ORG_ID/servers lists server ids. Paths use <org> for the organisation id and <server> for a server id throughout this reference.