login

POST

/auth/login

curl --request POST \
  --url http://localhost:8080/api/v1/auth/login \
  --header 'Content-Type: application/json' \
  --data '{ "username": "example", "password": "example", "client": "web", "deviceName": "example" }'

• Your Homestead (default port; replace with your address)

Request Body^required

Media typeapplication/json

object

username

required

string

password

required

string

client

required

string

Allowed values: web device

deviceName

string

<= 60 characters

Responses

200

Logged in. Web clients get a cookie; device clients get a token.

Media typeapplication/json

object

member

required

object

id

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

username

required

string

displayName

required

string

role

required

string

Allowed values: owner member viewer

locale

One of:

string

string

Allowed values: en zh-Hans th

null

null

theme

required

string

Allowed values: system light dark

textScale

required

number

>= 1 <= 1.6

reducedMotion

required

boolean

shareVisits

boolean

showAiSummaries

boolean

avatar

One of:

object

object

id

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

url

required

Signed URL, valid 24 h.

string

thumbUrl

string

cardUrl

string

posterUrl

string

mime

required

string

width

integer

height

integer

durationMs

integer

blurhash

string

alt

string

null

null

createdAt

required

string format: date-time

lastSeenAt

One of:

string

string format: date-time

null

null

csrfToken

Web clients only.

string

deviceToken

Device clients only. Shown once.

string

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "deviceToken": "hsd_demoDeviceToken0123456789abcdef",
  "member": {
    "avatar": null,
    "createdAt": "2026-10-07T09:00:00.000Z",
    "displayName": "Ben",
    "id": "mem_01j9706wfq8em7agb270vat3vp",
    "lastSeenAt": null,
    "locale": "zh-Hans",
    "reducedMotion": false,
    "role": "member",
    "shareVisits": false,
    "showAiSummaries": true,
    "textScale": 1,
    "theme": "system",
    "username": "ben"
  }
}

401

Missing or invalid credentials.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

code

required

string

i18nKey

string

detail

string

fields

Array<object>

object

path

required

string

code

required

string

i18nKey

string

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}

429

Too many requests. See Retry-After.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

code

required

string

i18nKey

string

detail

string

fields

Array<object>

object

path

required

string

code

required

string

i18nKey

string

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}

Headers

Retry-After

integer