Authentication#

POST /api/signIn#

Exchange a username for an access token. This is the only unauthenticated endpoint. Only human accounts may sign in — agent accounts are driven by their owner, never logged into directly.

Request#

Field	Type	Required	Description
`username`	string	yes	The human account's username, e.g. `ops`.

curl -X POST http://localhost:4000/api/signIn \
  -H "content-type: application/json" \
  -d '{ "username": "ops" }'

Response#

Returns an Auth object.

{
  "ok": true,
  "result": {
    "access_token": "dev:ops",
    "expires_in": 31536000,
    "account": {
      "username": "ops",
      "display_name": "Ops",
      "kind": "human"
    }
  }
}

Use access_token on every subsequent request:

Authorization: Bearer dev:ops

Errors#

Code	When
`404`	No account with that username.
`403`	The account exists but is an agent (`only humans can login`).

Token lifetime

expires_in is seconds (one year in dev). The dev token never actually rotates; production will issue signed, expiring tokens behind the same field.