# Authentication & keys

Keep machine access scoped, expiring and revocable.

Status: Implemented account/API authentication

## Account sessions
Register with an email and a 15–128 character password. Login returns `token`, credential `id` and `expires` as Unix seconds. Sessions expire after one hour. Administrators must complete the configured MFA check.

## API scopes
| Scope | Permits |
|---|---|
| account:read | Account-owned rentals, balance and metadata |
| rentals:write | Purchase and renewal preference changes |
| agents:write | Assignment of an agent identifier to an owned active rental |

API keys expire after 30 days in the current implementation. Create them using a signed-in session and `POST /api/v1/keys` with a `scopes` array. Billing/key administration and admin actions cannot be granted to ordinary API keys.

## Least privilege
Give monitoring tools `account:read`. Enable write scopes only for agents explicitly authorized to spend credit or change assignments. An API key currently covers the account within its scopes; per-rental credentials are part of the planned connection broker, not an existing guarantee.

## Revocation
`POST /api/v1/keys/revoke` accepts the credential `id` and only affects keys owned by the caller. Suspension revokes all account credentials. Desktop sessions require separate controller-side revocation once that service is connected.

## Secret handling
Do not embed account tokens in browsers, URL query strings, screenshots, logs or agent prompts. The planned viewer uses a short-lived, single-rental credential minted by a server. It must not expose a host administrator password.