Authentication

The API authenticates with an opaque bearer token (ApiToken). There is no
JWT, OAuth handshake, or API secret exchange — you mint a long-lived token and
send it on every request.

Get a token

Sign in to the FairCheck web app and open API Tokens (/api_tokens). Create a
token, give it a name, and copy the value immediately — it is shown only
once. Tokens are stored server-side as one-way hashes, so the full value can
never be displayed again; the API Tokens screen identifies each token by its
first 8 characters. A token identifies the user who created it and inherits
that user's account memberships.

Signing in via POST /api/v1/auth also returns a token — a fresh one on each
login (previous tokens keep working until revoked).

Send it

Put the token in the Authorization header as a bearer credential:

curl https://your-host/api/v1/payslips \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Requests without a valid token receive 401 Unauthorized. Each successful call
stamps the token's last_used_at.

Choosing an account

The token's user may belong to several accounts. The request is scoped to a
single account, resolved server-side (see
tenant scoping). To pick one explicitly:

curl https://your-host/api/v1/payslips \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "X-Account-Id: acct_abc123"

An account_id you are not a member of is ignored — you never gain access to
another tenant's data by guessing an id.

Keep tokens safe

A token grants the same API access as its user. Treat it like a password: store
it in a secret manager, never commit it, and revoke it from the API Tokens screen
if it leaks. Lost tokens can't be recovered (only hashes are stored) — revoke
and mint a new one.