Access Codes

An access code lets a controller reach an online host by typing a short code into the connect box — no need to know the host's address. There are two kinds, and the same input box accepts both; the server detects which was entered:

• Device code — a permanent code shown by every online host. Use it to reconnect to a host at any time.
• Support code — a short-lived access code minted on demand for temporary assistance. It may be redeemed again within its TTL for reconnects, and every redemption is audited. Minting a support code requires a central brain (the manager); a plain signaling server routes connections but does not issue support codes.

Redeeming a code

Enter the code in the connect box and submit (POST /api/desk/redeem-code). The server resolves it to the target host's live connection and returns a capability-scoped session. On the open-source signaling server a redeemed session is always capability-scoped — full, unrestricted control belongs only to the single-account owner signed in directly with the account credentials (session cookie), not to any redeemed code.

Each redemption carries an access ceiling — the capability limit the owner configured for that code (see below). The ceiling travels with every control request the controller makes during the session.

Per-code capability ceiling

The owner configures, per device code, a capability ceiling that bounds what a redeemed (non-owner) session may do. Each capability is three-state:

• Allow — permitted (still subject to the host's own global access settings).
• Ask — the host's local user is prompted at the moment the action is attempted.
• Deny — hard-denied.

Presets make this quick — View only (everything denied: screen view and read-only diagnosis), Assist (a middle ground), Full (everything allowed) — or set each capability individually: remote control, clipboard, private screen, whiteboard, terminal, file browse, file delete, file transfer.

File deletion is an independent destructive capability. Listing files and reading metadata requires File browse; deleting an entry requires both File browse and File delete. File transfer remains separate and controls uploads and downloads.

A code with no configured ceiling defaults to the restrictive all-ask posture (every capability prompts), never to full control.

How the effective permission is decided

A code's ceiling is only the upper bound. The capability actually in force for each action is the meet (the stricter) of three things:

1. the code's ceiling — what the owner allowed for this code;
2. the host's global access settings — [security] in config.toml; and
3. the live approval at the host — when the meet of (1) and (2) is left unset ("ask"), the host's local user is prompted. For a code / support session the answer applies to that request only: it is never persisted into the host's global access settings, so a borrowed session's on-device prompt can never widen what the owner configured (an owner's own session keeps the usual "remember" behaviour).

So Deny anywhere wins (hard-denied); an unset dimension on either side always prompts; and Allow on both the ceiling and the global setting is the only combination that passes without a prompt. Enforcement is entirely host-side — the ceiling returned at redemption is a UX hint for the controller, never the security boundary.

See also

• Global host access settings: config.toml → [security].
• The signaling-layer view of restricted sessions: Signaling Authentication.

Attempt limits

Adjust protection parameters under Settings → Device Codes → Access-code protection. Default mode limits redemption attempts per source network and applies temporary backoff after repeated unavailable codes. Wait before retrying when told there have been too many attempts. Changing Cookies or successfully redeeming a code does not clear failure history. Existing connections are unaffected. See Local Account and Initialization Security for limits and waiting rules. Standalone Signaling mode does not offer code redemption.

New device code length

Under Settings → Device Codes, set the generated length to a whole number from 6 to 64; the default is 8. First assignments and explicit regenerations use the new length. Existing devices keep their codes when reconnecting. Saving a length neither rotates existing codes nor revokes their grants.

For example, after changing 8 to 12, existing 8-character codes remain redeemable and new devices receive 12-character codes. Explicitly regenerating a device’s code gives it a new 12-character code, stops redemption of the old code, and prevents old grants from opening new connections.