Authentication and session

Who this request is, which workspaces it reaches and whether the installation still awaits its first access.

Answers 200 always, even with no credential at all: “there is nobody” is an answer, not a failure. It is how the interface decides between drawing the board, the login screen or the first-access screen.

curl -s http://localhost:3000/api/auth/session

const response = await fetch("http://localhost:3000/api/auth/session", {
  credentials: "include",
});

const { user, setupRequired, publicMode } = await response.json();

{
  "user": {
    "id": "cmt94cjx5000vql01imegem2r",
    "name": "Ana",
    "email": "[email protected]",
    "role": "ADMIN",
    "avatarUrl": null,
    "jobTitle": null,
    "timezone": "",
    "notifyBackupReady": true,
    "hasApiToken": true,
    "apiTokenCreatedAt": "2026-08-25T20:37:29.998Z",
    "apiTokenLast4": "mGQ",
    "passwordPending": false,
    "lastLoginAt": "2026-08-27T19:50:42.947Z",
    "createdAt": "2026-08-25T20:29:57.593Z",
    "tenants": [
      {
        "id": "cmsp4djx60002p801o7ybpkv7",
        "name": "Pessoal",
        "color": "amber",
        "role": "ADMIN",
        "membership": null
      }
    ]
  },
  "setupRequired": false,
  "publicMode": false
}

publicMode: true means the installation waives login: the identity is an anonymous visitor with role ADMIN and no record in the database.

Creates the FIRST account of the installation, which is born an admin.

The window in which this route accepts anything is exactly the interval between the installation coming up and the first account existing. After that, 409 forever, and there is no self-signup.

curl -s -X POST http://localhost:3000/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana",
    "email": "[email protected]",
    "password": "uma senha longa"
  }'

{
  "user": {
    "id": "cmt94cjx5000vql01imegem2r",
    "name": "Ana",
    "email": "[email protected]",
    "role": "ADMIN",
    "tenants": []
  },
  "setupRequired": false,
  "publicMode": false
}

The account created here becomes a member of every workspace that already exists, and the role does not come in the body: it is born ADMIN by definition.

Trades e-mail and password for a session, delivered in an HttpOnly cookie.

The cookie is SameSite=Lax and gets Secure according to how the request arrived: on a desktop install at http://localhost it has to be accepted, and behind a TLS proxy it has to be Secure.

# -c stores the session cookie in the given file
curl -s -c cookies.txt -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "password": "uma senha longa" }'

await fetch("http://localhost:3000/api/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  // The HttpOnly cookie is only kept if the request sends credentials.
  credentials: "include",
  body: JSON.stringify({ email, password }),
});

{
  "user": {
    "id": "cmt94cjx5000vql01imegem2r",
    "name": "Ana",
    "email": "[email protected]",
    "role": "ADMIN",
    "tenants": []
  },
  "setupRequired": false,
  "publicMode": false
}

To consume the API from outside, prefer the API token: Authorization: Bearer. The cookie takes precedence when both arrive together.

Ends the session of this tab.

Idempotent and with no identity required: signing out while already out returns 200.

curl -s -b cookies.txt -X POST http://localhost:3000/api/auth/logout

{ "ok": true }