Authentication and devices
The CLI uses RFC 8628 Device Authorization Grant. It prints a one-time user code and verification URL without requiring a browser callback on the machine, so it works from desktop terminals, SSH, Docker, and CI.
Complete first-device confirmation, QR trust, and revocation in the App when available. See App devices and security for the interface flow.
Sign-in flow
originrouter login --device-name "Studio Mac"
- The CLI requests a device code and stores a pending device security identity.
- It opens the browser by default and prints an 8-character user code.
- The user confirms the account and device on the verification page.
- The CLI polls for approval, then stores a rotating refresh token and purpose-specific short-lived access tokens.
The installation device ID is random and persisted locally. It is not derived from a MAC address, serial number, or machine ID.
Login flags
| Flag | Purpose |
|---|---|
--device-name <name> | Set the readable name in the account device list |
--no-browser | Print only the URL and code for SSH, Docker, or CI |
--surety-url <url> | Override the Surety OAuth root. The default comes from SURETY_BASE_URL or the production service |
--login-url <url> | Override the browser authorization-page root |
Headless example:
originrouter login --no-browser --device-name "Build runner"
The user code is a time-limited, single-use credential and must not be stored or reused as a durable credential.
Status, verification, and logout
| Command | Effect |
|---|---|
login status | Inspect local sign-in state |
auth status | Show an authentication-material and state summary |
auth verify | Verify current authentication against the service |
devices [--json] | List account-authorized CLI devices |
logout | Clear local sign-in material without requesting account-device removal |
logout --remove-device | Also request removal of the current device authorization |
security status | Inspect the device E2EE identity (not the Local API token) |
security rotate | Rotate device E2EE keys; sign-in is required |
For automation, use auth verify or supported --json output rather than parsing terminal prose.
Local API token
token show and local key show print the Local API Bearer token and URL.
These are separate credentials from the device E2EE identity shown by security status.
token rotate and local key rotate immediately invalidate existing local-client credentials. Reconnect the App and other Local API clients after rotation.
originrouter token rotate
Rotating the Local API token immediately invalidates existing local-client credentials.
Inspect the active daemon port:
originrouter daemon-port
security rotate requires an active sign-in. The running daemon adopts the new device key automatically, so service reinstallation is normally unnecessary.
Error recovery
| Symptom | Recovery |
|---|---|
| User code expired or polling timed out | Run originrouter login again for a new code |
| Authorization denied in the browser | Confirm whether the device should be added, then retry login |
| Device revoked or identity mismatch | Sign in again and authorize the new device identity |
| CLI version does not support the current E2EE protocol | Update the CLI, then sign in again |
| Account device limit reached | Revoke an unused device in the App, then retry |
| Daily key-rotation limit reached | Wait until the next UTC day |
Before signing in again, originrouter doctor can distinguish network, relay, and missing-local-file failures.