← API reference

Auth

Login, first-run setup, session state.

5 of 5 · v0.120.0
GET /api/v1/auth/status #
Public

Whether anyone is signed in, and whether this instance needs setup.

The SPA's gate. The only unauthenticated read in the API.

Responses

200

OK.

application/json

object

Whether anyone is signed in here, and whether the instance has been set up.

needs_setup boolean required

True until the first admin exists. There is no self-registration.

False when the database cannot be asked: "no users yet" is only ever reported when it is known to be true.

authenticated boolean required

Whether the request carried a valid session cookie.

is_admin boolean required
POST /api/v1/auth/setup #
Public

Create the first admin account.

First run only — refused once any user exists. Returns a session cookie and an API token, the latter shown exactly once.

Request body required

application/json

object
username string required
password string required

At least 8 characters.

display_name string | null

Responses

200

Created. Sets td_session.

application/json

object

The first admin, signed in, with a token.

user_id integer · int64 required
username string required
token string required

An API token with submit and read. Shown once, never again.

message string required
400

Malformed or rejected input.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

403

Already set up.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

POST /api/v1/auth/login #
Public

Sign in.

Sets the td_session cookie. Rate limited on repeated failure.

This is the mobile flow. Post credentials once, then mint a named token and store that — the cookie expires hard at 7 days with no sliding renewal, and cannot be revoked per device.

Request body required

application/json

object
username string required
password string required

Responses

200

Signed in. Sets td_session.

application/json

object

Who is signed in.

user_id integer · int64 required
username string required
is_admin boolean required
401

Bad credentials, or the account is disabled.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

429

Too many failed attempts from this address. Retry-After says how long to wait.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

POST /api/v1/auth/logout #
Session

Sign out.

Clears the session. The clear cookie carries identical attributes to the one that was set — mismatched attributes make logout silently fail. Never fails: with no session it only clears the cookie.

Responses

200

Signed out. status is logged out.

application/json

object

An acknowledgement with nothing else to report.

status names what happened — ok, updated, deleted, cleared, started and so on; the operation says which it sends. A client needs only the HTTP status to know it worked.

status string required
GET /api/v1/auth/me #
Session

The signed-in user.

Responses

200

OK.

application/json

object

Who is signed in.

user_id integer · int64 required
username string required
is_admin boolean required
401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}