Officials & sessions

Every write to a HardState Log is authorized by signature — there are no API keys and no server-side write sessions. This page covers who holds the keys: officials with passkeys, the sessions they open, and the system keys for processes with no person behind them.

Who signs

Signer	When to use	How it is authorized	Attributed to
Session of a person (role: session)	A clerk’s or inspector’s workstation, tablet, or field app during their shift	The person approves it once with their passkey (session.open); it expires (≤ 30 days)	That person, by name
System key (role: system)	A process with no person behind it: a payment gateway, an appointment system, a scanner	An admin registers it once (key.add), limited to some step types	The system, by name
Passkey, step by step	Low volume, or high-stakes acts that must be signed in person	Already registered in the institution’s log	That person

Prefer sessions for anything a person is responsible for: accountability stays personal, and a lost device is closed in one click. Use system keys only for steps that no person performs, and always scope them.

Passkeys, not crypto

Officials sign with the passkey already on their device — Face ID, Touch ID, a Windows Hello PIN, a phone, or a hardware security key. There are no wallets, no tokens, no seed phrases. A passkey is a WebAuthn credential bound to the institution’s domain; the private key never leaves the device.

Enrolling an official

1. Invite. An admin sends an invitation link from the console, or enrols the official from the same device.

2. Create a passkey. The official opens the link and creates a passkey with their device’s own prompt.

3. Approve. An admin approves the new key. It is now recorded in the log (key.add) and allowed to sign.

Sessions: sign once, work all shift

Signing every single step with a passkey prompt does not scale to a day of counter work. Instead the official opens a session:

1. The official opens a session with a single passkey tap (session.open). They can scope it to certain step types and set how long it lasts (up to 30 days).

2. For the rest of the shift, “Record a step” signs with the session key — no prompt per step.

3. The session closes itself when it expires, or the official (or an admin) closes it from the console at any time.

Steps signed through a session are attributed to the person who opened it, by name. This is how an institution’s own software records checkpoints automatically: the official authorizes the software’s key as their session once, and the software signs each step after that. See API integration.

System keys for unattended processes

When no person performs a step — a payment gateway confirming a fee, an appointment system opening a case — an admin registers a system key (key.add) instead of a session. It is valid until revoked, attributed to the system by name, and should always be scoped to the narrowest set of types that works (for example, ["fee.paid"]).

If a key leaks

Close the session or revoke the system key from the console. Everything signed before the key was revoked stays attributable — that is the whole point of a signed, anchored log. Nothing signed after revocation is accepted.

Custody

Session and system private keys never leave the machine that uses them: a file with 0600 permissions, or better an HSM or a cloud KMS. Passkey private keys never leave the official’s device. HardState never sees any private key, and never needs to.

Next Ready to wire this into your own software? Head to API integration.