# Users and access Electric Cherry requires a user session for operator pages and management APIs. HTTPS protects the connection; server-side role checks protect each operation. There is no anonymous management mode or public registration. Leaderboard API reads (`GET` and `HEAD /api/leaderboard`) are public and need no session or credentials. This exception covers only that exact API route; leaderboard/profile pages, match-history routes and management operations retain their access checks. HTTPS requirements still apply. See the [leaderboard API reference](leaderboard.md#read-api) for requests and response fields. ## First administrator and upgrades 1. Generate a setup secret: `openssl rand -hex 32`. 2. Set `EC_SETUP_TOKEN` to that value in the controller environment (or Compose `.env`), set `EC_PUBLIC_URL` to the external HTTPS URL, and start EC. For a direct Node deployment, set `ORIGIN` to that same URL. 3. Visit EC. `/setup` asks for the setup token, a username, display name and password. Only the holder of the token can create the first administrator. 4. Remove `EC_SETUP_TOKEN` after setup and restart/recreate the controller. Setup remains closed once any user exists, even if the token is still set. 5. Use **Admin → Users** to create additional accounts. Share temporary passwords privately; each user must change theirs on first login. Existing installations become protected on upgrade. Existing game servers and agent enrollment credentials continue working independently of browser login. Preserve the current database when upgrading: accounts and sessions are stored there alongside the fleet metadata. Never publish a blank setup page with a guessable token. An unset setup token holds setup closed. ## Roles The Moderator role has Viewer-level fleet access plus private player moderation. It permits live player actions, case review and server/game restrictions lasting up to seven days, without granting fleet operations or access to raw configs and credentials. Administrators also control permanent/fleet restrictions, integration configuration and revoking another moderator's restriction. Super Viewers can read moderation; Operators and Viewers cannot. See [Player moderation](moderation.md). | Capability | Viewer | Super Viewer | Operator | Administrator | | --------------------------------------------------------------------------------------------- | -------------- | ------------ | ----------- | ------------- | | Fleet, metrics, matches and operation summaries | Yes | Yes | Yes | Yes | | Raw configs, file diffs, logs, saved RCON and telemetry diagnostics | No | Read | Read | Read | | Deploy/start/stop/restart/rebuild/remove servers and run diagnostic probes | No | No | Yes | Yes | | Scripts, plugins, configs, campaigns, betas and collections | Read summaries | Read | Manage | Manage | | Host setup, deletion, enrollment, credentials, runtime preparation and game-file upload/cache | Read status | Read status | Read status | Manage | | Server keys and global settings/maintenance policies | No | Read | No | Manage | | Users and account audit activity | No | Read | No | Manage | | Create users, change roles, disable accounts and reset passwords | No | No | No | Yes | | Own password and sign out | Yes | Yes | Yes | Yes | Super Viewer is a read-only administrator. It includes the Admin navigation and access to sensitive configuration and diagnostic content, but cannot change fleet state, settings, keys, or other accounts. Cleanup previews remain available because they do not save settings or run cleanup. Assign it only to people trusted to read administrative information. Existing accounts and sessions are preserved on upgrade. Operators can launch using available game-pool keys already saved by an administrator. They cannot save keys indirectly through a launch request. An operator's content permissions include executable scripts and plugins; assign that role only to people trusted to operate the game fleet. Drift previews (`/api/drift`) and GitHub release lookups (`/api/plugins/github/release`) require operator or administrator access, including `GET` and `HEAD` requests. These endpoints initiate fleet file scans or use GitHub API quota; Viewers and Super Viewers cannot trigger them. Saved RCON failure replies are available to Super Viewers, operators and administrators in the server's Diagnostics tab. Player addresses are redacted before diagnostics are saved; successful checks clear the saved reply. Fleet snapshots and live status streams contain no reply snippets. Upgrades discard older saved RCON snippets. Permissions are checked on the server for API calls, normal pages and Svelte page-data requests. Hiding UI controls is a convenience, not the access boundary. The controller prevents disabling or demoting the last enabled administrator. Accounts are disabled rather than deleted so history retains their identity. ## Passwords, sessions and recovery Passwords are 8–128 characters and stored using salted scrypt hashes. Temporary passwords created or reset by administrators must be changed before any fleet access. Password changes require the current password. Sessions use random tokens in HTTP-only cookies, with only token hashes stored in SQLite. HTTPS uses a Secure `__Host-` cookie. By default, sessions expire after 12 hours, or 30 minutes without authenticated requests; background dashboard polling counts as activity. Select **Keep me signed in on this device** at sign-in to stay signed in for 30 days, including between visits from a phone's home-screen app. This option is unchecked by default and applies only to that browser or home-screen app. Remembered sessions have no inactivity timeout, but still expire 30 days after sign-in; activity does not extend that deadline. Use this option only on a device you trust. Existing sessions keep their original limits after upgrading. Password changes always require the current password. Remembered administrator sessions also require the administrator's current password when creating accounts or editing users, including access changes and password resets. A successful password change replaces the current session, preserving its remember-device choice with a fresh lifetime, and revokes all other sessions. For API clients, `POST /api/auth/login` accepts an optional boolean `rememberMe` (omitted or `false` keeps the default limits). When using a remembered session, `POST /api/users` and `PATCH /api/users/:id` require the administrator's password in `currentPassword`; the `password` field remains the target user's temporary password. The password-change endpoint preserves the current session's choice. Login replaces the existing browser session. Logout revokes it. Changing a password, changing a role, disabling an account, or revoking that user's sessions invalidates their existing sessions. Live event streams check revocation every 15 seconds and then close. Login and password changes for enabled Administrators and Super Viewers are exempt from per-account and per-address rate limits, including existing exhausted windows. Their attempts do not consume either limit. Other accounts and initial setup use persistent 15-minute windows. Exemptions use the account's current database role; password verification is still required. The database stores audit entries for login results, account changes and successful management requests without recording passwords, tokens or request bodies. Administrators and Super Viewers can review recent entries in Users. For every role, the password service runs at most two scrypt operations at once and queues up to 16 more for up to two seconds. If that queue fills or the wait expires, the request returns HTTP 429 with `Retry-After: 2`. The persistent rate limits return `Retry-After: 900` when a non-exempt account or address reaches its attempt limit. An administrator can reset another user's password from Users. If the only administrator forgets their password, an operator with local controller/container access can run the recovery command in an interactive terminal: ```sh docker compose exec electric-cherry node scripts/reset-admin.mjs admin # Direct Node deployment, using the correct database: DB_PATH=./data/cherry.db node scripts/reset-admin.mjs admin ``` Replace `admin` with the existing administrator's username. The command prompts without echoing the password, resets that enabled administrator only, revokes their sessions and records the recovery. It does not expose a remote recovery endpoint or accept passwords as command arguments. ## Agent and telemetry connections Host agents retain enrollment/host-token authentication under `/api/agent/`. Installer and release files remain public so a new machine can enroll. A browser login never substitutes for a host credential, and host tokens cannot manage EC. The agent and standalone updater source contain no credentials. Automatic updates fetch the controller's public HTTPS release manifest and verify its checksums and compatibility. The installed host retains its own credential; the updater accepts an upgrade only after a fresh authenticated heartbeat from the new agent process. Updating agent code does not change browser sessions or user roles. See [automatic agent updates](native-hosts.md#automatic-agent-updates) for the one-time installer upgrade required by existing hosts. Host deletion uses a separate operation-scoped receipt token so the uninstall worker can confirm removal and retry its acknowledgment after host credentials are revoked. That token authorizes only the corresponding cleanup receipt. Game reporters must send a separate secret of at least 32 characters configured as `EC_TELEMETRY_TOKEN`: ```http POST /api/telemetry Authorization: Bearer Content-Type: application/json ``` `X-EC-Telemetry-Token` is also supported. Cookies, query parameters and JSON fields cannot supply it. A missing server token disables ingestion; a missing or wrong request token is rejected before parsing or recording the payload. Existing JSON event fields are unchanged. Configure your uploaded reporter/plugin, or a trusted relay if that reporter cannot set headers, before upgrading. Use HTTPS for the reporter-facing endpoint. Rotating this shared token requires updating reporters. ## Proxy and local development Keep Node's internal port behind your TLS proxy and configure `ORIGIN` correctly. Management writes require an exact matching `Origin` header, including login, JSON requests and multipart uploads. Do not configure a proxy to replace arbitrary incoming origins with your trusted origin. Machine endpoints use their own token checks and do not require a browser Origin. Use the adapter's real client-address configuration only with a trusted proxy that strips spoofed forwarding headers; login throttling otherwise uses the direct peer address. Forwarded host or user headers do not authenticate users. Local HTTP browser development requires `EC_AUTH_ALLOW_HTTP=true` and a loopback hostname (`localhost`, `127.0.0.1` or `::1`). This uses a separate development cookie. It never enables HTTP login for a LAN/public hostname. Agent HTTP development remains separately controlled by `EC_AGENT_ALLOW_HTTP` and the agent's loopback-only option. The implementation follows OWASP's guidance for [authorization on every request](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html#validate-the-permissions-on-every-request), [password hashing](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#scrypt), and [session management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html).