# Licences, devices & 402s

## How licensing works
A licence attaches to your CHYNJ ACCOUNT EMAIL. A device is "connected" when its fingerprint is registered against the licence (Kaptain does it at activation; only a SHA-256 of the fingerprint leaves the machine). The account portal (https://chynj.ca/account) is the source of truth — key + device list live there even if the licence email never arrived (spam: noreplycode@chynj.ca).

## Activate
- Option A — sign in (recommended): wizard Account step, the account the licence is on (2FA if enabled). Licence found by email, applied, device registered + certificate enrolled in one act; the box re-checks the account every few hours so renewals apply themselves.
- Option B — paste the key: Plan step > "Have a license key?" > KAPTAIN-XXXXXXXX-XXXX-XXXX. For when only the key travelled.

## Restore after a trial (incl. remote)
Trials bind to the MACHINE. Never reinstall — licence/sign-in screens stay reachable when expired. Sign in (durable) or paste the key on the "Trial expired" screen. Remote: http://<tailnet-address>:8810, or SSH in and open localhost:8810.
Headless: `kaptain device register` (--nickname, --no-browser, --json) — prints URL + short code, approve from any browser, prints the access code ONCE, then `kaptain stop` then `kaptain start`. Nothing pasted into the command; no password in the CLI. `kaptain account` = status|open only; `kaptain license` = status|refresh only.

## Devices, limits & offline
Pro = up to 5 devices; 6th refused until a slot is freed (portal > Devices > Sign out; that box drops out of Pro until re-activated). Validation: at startup + ~every 4h; offline runs on a signed local cache and re-validates when back.

## Troubleshooting
No licence email -> key is in the portal. "No license found" -> licence is on a specific email. "Device limit reached" -> sign out an old device. "Invalid key" -> re-copy with the Copy button (stray spaces).


A release build proves entitlement with a signed device certificate at every start. 402 = this machine can't prove it. Fix for the common case = one command + one click.

## Every cause (and the right fix)
- Never bound (the common one): fresh install, sign-in skipped -> `kaptain device register` (below)
- Device revoked: deleted in the account portal -> re-register
- Lease expired: offline too long for the background refresh (short outages are fine) -> reconnect; it renews itself; still 402 -> re-register
- Moved to new hardware: data folder copied to a different machine; the certificate binds to the original installation -> register the new machine
- Trial ended: server stops issuing leases -> subscribe/restore in the portal, then refresh
- Clock skew: lease "isn't valid yet" -> fix the system clock
- Build below minimum version: leases can require a minimum safe version -> `kaptain update`

`kaptain device status` / `kaptain license status` print exactly which state this machine is in. Dev builds without compiled trust keys don't run this gate — 402 is release-build behaviour.

## The fix
1. On the Kaptain machine: `kaptain device register` — prints a short pairing code and waits.
2. Open https://chynj.ca/account (any device), sign in, approve the code.
3. The command writes the device certificate AND a fresh access code (chynj_..., shown once — save it; every paired device re-pairs once with it).
4. Restart if running: `kaptain stop` then `kaptain start`.

Unapproved codes expire — rerun the command for a fresh one.

## Afterwards
- The machine appears under Devices in the account portal (removable there).
- Entitlement refreshes in the background; brief network loss is fine.
- Website updates (Settings > Update Kaptain) install signed builds that keep working.

## Why pasting a licence key isn't enough
A key activates a PLAN; the certificate proves THIS MACHINE may use it. Key-paste alone never certifies — sign in at setup or `kaptain device register`. Full detail: https://chynj.ca/kaptain/docs/how-to/fix-402/