Sign-in, users and API tokens¶
People sign in to TandemApp with an account. Programs use an API token. Nothing else opens it: there is no shared admin password, no open default for other devices, and no trust for a request because it comes from the same machine, except in local mode (below).
The answers of every route on this page are in contracts/auth-v1.
Roles¶
Each role holds the permissions of the roles above it in the table.
| role | may |
|---|---|
| viewer | read every page, the fleet and the metrics; use models from the page; manage their own sessions and password |
| operator | change settings and the fleet, use the Chat tab, make API tokens |
| admin | trust engine hosts and nodes (pairing, take-over); manage every account but the owners, every session and every token |
| owner | manage owners, the identity provider, the API exposure switches and the auth and api settings |
auth.chat_min_role: viewer opens the Chat tab to viewers. api.tokens.viewers_may_create: on
lets viewers make inference tokens. The last enabled owner cannot be disabled, demoted or
removed.
The first owner¶
Local mode. A TandemApp process bound to loopback only (127.0.0.1, ::1), not in a
container and not on Kubernetes, opens to this machine's browser and tools as the owner local
until that owner sets a password. Nothing else on the network reaches it. A tool on this machine
needs no API key: a made-up key counts as none, while a known token stays itself and a revoked or
expired one gets 401. Setting the password ends local mode at once. TANDEM_LOCAL_MODE=off or the
setting auth.local_mode: off turns it off.
The setup code. Everywhere else nobody signs in until the first owner exists: every route but
/health, the page and the sign-in answers 401. The page asks for a one-time setup code, a name
and a password. The code is 20 characters (case, spaces and dashes do not count), opens only the
setup, and is spent after one use or five wrong tries. Get one from:
- the installer's summary (
--listenbeyond loopback, or--behind-proxy); - the controller's log: each start without an owner logs a fresh one, valid 24 hours;
tandem-app users setup-codeon the controller's machine;- on Kubernetes, the chart's Secret or
kubectl exec ... tandem-app users setup-code(install-kubernetes.md).
tandem-app service install --host 0.0.0.0 refuses while no owner has a password, unless
--setup-code, which prints a code.
Sessions¶
A sign-in (POST /v1/auth/session) sets a cookie: __Host-tandem_session over https,
tandem_session over http, HttpOnly, SameSite=Strict. A session ends when it is signed out or
revoked, after auth.session.idle_days (30) without use, or auth.session.absolute_days (180)
after it began. The server keeps only a hash of the id.
Every write of a session sends the X-Tandem-CSRF header from the sign-in's answer, comes from
the same origin, and declares a JSON body (a file upload excepted). A WebSocket and an event
stream are refused from another origin.
A changed password ends every other session of the account. Disabling an account, lowering its role or removing it ends its sessions at once.
Limits. Five failed sign-ins a minute per address, then 429 for a minute. After five failures for one name, each further try waits twice as long as the one before, from 2 s up to 300 s, never a lock for good. An unknown name costs the same as a wrong password. Twenty wrong API tokens a minute per address, then every request with a token from that address is 429 for the rest of the minute.
Behind a reverse proxy, name the proxy in TANDEM_TRUSTED_PROXY (addresses and CIDR ranges,
comma separated): only then do its X-Real-IP and X-Forwarded-Proto count, so the limits key
on the client and the https cookie is set. Loopback is always trusted for these two headers.
API tokens¶
A token is tdm-<8 hex id>-<43 characters>. It is shown once when it is made and stored as its
sha256. Make one with New API key on API, Endpoint and keys (or Create a token on the Access
page), with POST /v1/auth/tokens, or with tandem-app tokens create NAME --label L --scope S.
The dialog asks what the key is for (a coding agent, a Messages API client, a chat app, a script,
monitoring) and fills in the scopes, then which backends and models it may run, then its expiry
and limits, and shows the key once with the setup for that client.
| scope | opens |
|---|---|
inference:openai |
the OpenAI-compatible routes: chat and text completions, embeddings, responses, the cache routes, the model list |
inference:anthropic |
the Messages API (/v1/messages, count_tokens) and the model list |
usage:read |
the ledger's views |
metrics:read |
the metrics and the ledger's views |
settings:read, settings:write |
the settings |
fleet:read, fleet:write |
the fleet |
trust |
pairing and take-over |
backends narrows a token to those backends (SRV-889): a request goes only to a backend on the
list, a route's fallbacks keep only those, and a model the token may not reach is a 403 that names
the backend. models narrows it to model ids that match its globs (small-*), or to
<backend>/<model> globs over the backend that serves the model (vllm1/*,
openrouter/anthropic/*). Both empty: every backend and model. /v1/models lists a token only
the models it may run. days sets its expiry, or
never. limits holds requests_per_minute, tokens_per_minute, concurrent, cost_per_day
and cost_per_month: a rate limit is a 429 with Retry-After, a spend limit a 403
spend_limit_reached. An admin sets defaults per role (api.limits.default.<role>.<key>); a
token never has more than its owner's role allows, checked at each request, so a demoted owner's
token loses the rights at once.
A token never manages tokens and never signs in to the page. Rotate it with
POST /v1/auth/tokens/{id}/rotate {grace_s}: the new secret works at once, the old one for
grace_s more seconds. A revoked token's open streams are closed.
A client's Authorization or x-api-key never reaches a backend: the gate checks it and removes
it.
Service identities. chatd, a backend's collector and the plugin relay have identities of their own, which no role holds. Being on the same machine opens nothing for them.
Who may use the API from other devices¶
One switch per protocol, on Settings, API: api.openai.exposure and api.anthropic.exposure.
| value | who |
|---|---|
this-machine (the default) |
service identities, the page's own calls, and callers on this machine (with a token, outside local mode) |
network |
the above, plus any device with a token that holds the protocol's scope |
No value lets a device in without a token. A call from another device while the switch is
this-machine is 403 api_not_exposed. A controller bound to loopback is not reachable from other
devices whatever the switch says: change api.listen too (applied at the next restart). On
Kubernetes the chart's ingress decides which paths arrive at all. The health page names an exposed
protocol no token can use, one the listener or the ingress cannot reach, and tokens sent over plain
http from another device.
Clients¶
An OpenAI-compatible client takes the API's address and a token:
export OPENAI_BASE_URL=https://tandemapp.example.lan/v1
export OPENAI_API_KEY=tdm-...
curl $OPENAI_BASE_URL/chat/completions -H "Authorization: Bearer $OPENAI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "small-1", "messages": [{"role": "user", "content": "hi"}]}'
A Messages API client takes the server's address (without /v1) and a token with
inference:anthropic, sent as x-api-key or as a bearer:
export ANTHROPIC_BASE_URL=https://tandemapp.example.lan
export ANTHROPIC_API_KEY=tdm-...
curl $ANTHROPIC_BASE_URL/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" \
-H 'anthropic-version: 2023-06-01' -H 'Content-Type: application/json' \
-d '{"model": "small-1", "max_tokens": 64, "messages": [{"role": "user", "content": "hi"}]}'
Refusals come in the protocol's own shape: {"error": {type, code, message}} on the OpenAI
routes, {"type": "error", "error": {type, message}} with a request-id header on the Messages
API.
Recovery¶
| what | do |
|---|---|
| a person lost their password | an admin on the Access page (Accounts); or on the controller's machine tandem-app users reset-password NAME. The answer is a one-time code, valid 24 hours: sign in with it as the password, then set one. The old password and every session of the account stop at once |
| the only owner lost the password | tandem-app users reset-password NAME on the controller's machine (on Kubernetes through kubectl exec) |
| no owner yet, the code is lost | restart the controller (its log holds a fresh code) or tandem-app users setup-code |
| a token leaked | revoke it (the Access page, or tandem-app tokens revoke ID); its open streams close |
| an account must stop now | disable it: its sessions end and its tokens stop at the next request |
The users and tokens commands work on the config database in the state directory and ask for
no password: whoever can read that directory is the owner already.
Routes¶
GET /v1/auth/session who this request is: account, role, permissions, CSRF token,
provider, setup_required, local_mode
POST /v1/auth/session {username, password}: the session cookie
DELETE /v1/auth/session sign out
POST /v1/auth/setup {code, username, password}: the first owner; 404 once one exists
PUT /v1/auth/password {current, password}
GET /v1/auth/sessions[?user=] the live sessions; DELETE ends them, DELETE .../{id} one
GET /v1/auth/users the accounts; POST makes one, PATCH /{id} changes one,
DELETE /{id} removes one, POST /{id}/reset a one-time code
GET /v1/auth/audit sign-ins, sessions, accounts, tokens and the auth settings
GET /v1/auth/tokens[?all=1] tokens; POST makes one, PATCH /{id}, DELETE /{id} revokes,
POST /{id}/rotate, GET /{id}/usage
GET /v1/auth/usage[?user=] what an account used
Moving from the old sign-in¶
An older install's secrets are imported once, at the first start of this release:
| before | after |
|---|---|
the admin password (admin.json) |
the account owner with that password |
TANDEM_ADMIN_TOKEN (or QSE_ADMIN_TOKEN), TANDEM_ADMIN_TOKEN_FILE |
a management token for scripts that ends after 30 days, under review, never a sign-in. With no admin password it works once as the setup code first |
TANDEM_API_KEYS, the keys of TANDEM_API_USERS_FROM's database, the users table |
an API token each with the same hash, under review until an admin confirms it; the OpenAI exposure starts at network so their clients keep working |
TANDEM_DASHBOARD_LOGIN, --dashboard-login, --trust-loopback, TANDEM_AUTH |
nothing: read by nothing |
the qse_dash cookie |
nothing: sign in again |
A variable left in app.env is named on the health page (legacy_env_set) and never stops the
start; remove it once you will not go back. Going back to the release before works on the same
state: its tables are untouched, a key revoked here is disabled there too, and once a token exists
the release before refuses requests without a key instead of opening them.
The engine's own sign-in (QSE_ADMIN_TOKEN on the engine's port) is the engine's and is not part
of this.