API Tokens

API tokens are credentials for hosts / automation to access the manager. Every signed-in user can self-manage them on Account → API Tokens.

Uses

• Host registration — a host connects to the manager with a personal token and is bound as the device owner (this determines device ownership; see Device Access Authorization).
• Automation / integration — scripts or external systems access the manager API with a token.

Mobile hosts: automatic issuance

When a mobile client (Android) signs in with an account/password and starts hosting (screen share), you do not need to create a token by hand: the client automatically calls POST /api/tokens to issue a personal token, caches it, and uses it to connect to manager signaling, register the device, and bind ownership. Without this token the host is adjudicated as an anonymous browser and cannot be managed.

• The token is issued per user (not per device) and appears on this page; an auto-issued host token's name carries device info (like mobile-host · Manufacturer Model) so you can tell which token belongs to which device.
• After revocation, a host that has never proved the credential may attempt one automatic reissue. A host that already established a Manager credential lease does not silently replace it: related sessions are closed first, then the host waits for a token update or manual retry.
• The automatic reissue runs at most once per cycle: if the freshly issued token is refused too (the session expired, or the token cap prevents issuance), the host stops auto-reconnecting and shows a notice plus a Retry button, so a dead token cannot burn through your token quota.
• Signing out on mobile clears the locally cached token.
• When the limit is reached: automatic issuance stops and the app shows "API tokens are full." You can then list your existing tokens on mobile and delete unused ones to free a slot (issuance resumes automatically), or paste an existing full token to continue.

Quota (count limit)

The number of API tokens a user may hold is capped, sharing the same threshold as the device-count quota (system parameter device.quota.default, default 5).

• The count includes every non-expired token — enabled and disabled both occupy a slot; only deleting a token (or its natural expiry) frees a slot, disabling does not.
• Once the cap is reached, creation is refused (a business error code; HTTP stays 200, with the reason shown inline).
• The open-source signaling server has no such cap, so this limit only appears when connecting to the manager.

Managing Tokens

On Account → API Tokens:

• Create a new token (store it safely; it is typically shown only once at creation).
• View existing tokens and their status.
• Enable / disable a token; disabling puts related hosts into a recoverable suspension, so it asks for confirmation first.
• Delete tokens no longer in use — only deletion frees a quota slot.

Live Sessions, Suspension, and Rotation

• Deleting or expiring a token, or moving its owner into an irreversible deletion stage, starts session invalidation. Sessions normally disconnect within about 90 seconds; even if the notification is lost, the host-local credential lease enforces a hard three-minute maximum.
• Disabling a token or account, or entering a cancellable deletion grace period, tears down sessions once detected but keeps the original token for bounded suspended recovery. After restoration, the host reconnects automatically within at most about 330 seconds; Retry probes immediately.
• During a short Manager backend outage, established sessions may continue inside the 120-second local lease. New desktop or terminal admission is temporarily refused and controllers retry at adjacent 2/5/10/20-second intervals, for a 37-second window before offering manual retry.
• Replacing a host's Manager API token creates a new credential scope. Proof for the new token never extends sessions created by the old token; old sessions disconnect within 120 seconds and are not resurrected.

Security Tips

• One token per use, so you can revoke by purpose.
• Never put tokens in logs, screenshots, or commits.
• Revoke and rotate immediately if you suspect a leak.

Related

• Ownership & authorization: Device Access Authorization.
• Personal AI config: AI Gateway.