Authentication

Homestead has four kinds of credentials. All tokens are 32 random bytes, base62-encoded, with a prefix that says what they are. The server stores only their SHA-256 hashes.

Credential	Prefix	Who	How to send it
Session cookie	hs_session	Web app	Cookie, plus X-CSRF-Token on writes
Device token	hsd_	Phone app, Firefox companion, scripts acting as a member	Authorization: Bearer hsd_…
Agent token	hst_	Hermes, OpenClaw, scripts	Authorization: Bearer hst_…
Capture upload token	hsu_	Homestead Helper	Authorization: Bearer hsu_…

Session cookie and CSRF (web app)

Sign in with "client": "web":

curl -X POST http://localhost:8080/api/v1/auth/login -H "Content-Type: application/json" -d '{"username":"mali","password":"your-password","client":"web"}'

The reply sets the hs_session cookie (HttpOnly, SameSite=Lax, and Secure over HTTPS) and returns a csrfToken. It’s also readable later from GET /api/v1/me.

Every write with the cookie (anything other than GET, HEAD or OPTIONS) must:

• send X-CSRF-Token equal to that csrfToken, and
• come from the same origin. When HOMESTEAD_BASE_URL is set, the Origin header must match its scheme and host exactly. Otherwise 403 forbidden.

A web session lasts 30 days and renews while used.

Device tokens (hsd_)

A device token acts as the member who created it, with that member’s role. Bearer requests don’t need CSRF.

• Sign in with "client": "device" (and an optional deviceName); the reply carries deviceToken, shown once.
• Or pair: a signed-in member creates a pairing code with POST /api/v1/auth/pairing-codes (10 minutes, 8 characters, QR payload homestead://pair?server=<baseUrl>&code=<code>), and the device sends it to POST /api/v1/auth/pair with a deviceName.
• The Firefox companion pairs the same way with "client": "extension".

Device tokens last 365 days and renew while used. POST /api/v1/auth/logout ends one.

Agent tokens (hst_)

Created by a member on the Agents screen, with POST /api/v1/agent/tokens, or with homestead token create on the server. The token and a ready-made setup block (REST base URL, MCP URL, Hermes YAML, OpenClaw JSON5, an env block) are returned once.

{
  "name": "Hermes on homeserver",
  "agentKind": "hermes",
  "preset": "fetcher",
  "platforms": ["instagram", "douyin"]
}

Agent tokens never get household administration: members, invites, tokens and source settings are off limits. An operation without x-required-scopes refuses agent tokens with 403 agent_not_allowed; one whose scope the token lacks gives 403 scope_missing.

Scopes

Scope	Allows
people:read	List and read people, accounts, platforms
people:write	Resolve input, quick-add, create and edit people and accounts
circles:read	List and read circles
circles:write	Create and edit circles and membership
shares:write	Create share links and import circle packs
feed:read	Read feed, story rail, moments
tasks:work	Lease and complete agent tasks
ingest:write	Push moments and upload media

Presets

Preset	Scopes
fetcher	people:read, tasks:work, ingest:write
helper (default)	All scopes except shares:write
full	All scopes

scopes, when given, overrides preset. platforms limits which platforms’ tasks the token can lease.

Each use updates the token’s last-used time, shown in the app. Revoke with DELETE /api/v1/agent/tokens/{tokenId}; its leased tasks return to the queue.

Capture upload tokens (hsu_)

Note

The captures API is part of the spec but returns 501 on main until task S-16 lands.

createCapture returns an hsu_ token valid for 10 minutes, for uploadCaptureAsset on that one capture only. Operations that accept it are marked x-capture-upload in the spec.

Member roles

Role	Can
owner	Everything, including household settings, members, source settings and agent tokens
member	Add and edit people, accounts, circles, shares; create agent tokens; invite viewers
viewer	Read feed, stories, people, circles; mark seen; record visits; snooze; edit own profile

Each operation lists its minimum role as x-min-role. Public operations (x-public), such as health, setup, login, pair, invite preview and the public share, need no credentials.

Sign-in limits

Login, pair and accept-invite are limited to 10 a minute per IP. Five failed logins lock that username for 15 minutes. See Conventions.