REST API Reference

The complete endpoint catalogue for the Lab Kiosk Cloudflare control plane, plus the client agent's loopback API.

Endpoints below are verified against cloudflare-control/src/index.ts. Where the in-repo docs/API.md and the implementation disagree, this page follows the implementation — see Known documentation drift.

Conventions

• Protocol: HTTPS only in production, enforced by HSTS and edge redirection.
• Content type: application/json; charset=utf-8, except for HTML pages and redirects.
• Caching: API responses carry Cache-Control: no-store and X-Content-Type-Options: nosniff.
• Errors: { "error": "<human-readable message>" } with the appropriate status.

Authentication schemes

Session tokens are random 32-byte hex strings; only their SHA-256 hash is stored in D1. Device tokens are handled the same way — the plaintext token exists only on the workstation that was issued it.

Guards

Every route passes through src/guard.ts before its handler runs:

Rate limiting

• Sign-in: repeated failures trigger exponential back-off per identifier, answered with 429 Too Many Requests.
• Registration and failed enrolment: throttled per source address via rateLimitWait() / recordRateLimitHit() in db.ts.

Payload limits

• Thumbnails: capped at 256 KB. Anything larger, or not prefixed data:image/jpeg;base64, or data:image/png;base64,, is dropped server-side. The agent drops oversized frames before sending, so the heartbeat still lands.
• Lock messages: truncated to 280 characters.
• VNC passwords: truncated to 64 characters (x11vnc itself uses only the first 8 — see Remote Control).
• Client identifiers: must match ^[A-Z0-9][A-Z0-9_-]{0,63}$ (enrolment in index.ts, the hub in org_hub.ts). The agent is stricter, {0,62}, so a wizard-chosen id always passes.
• URLs: every navigable URL passes safeHttpUrl(), which accepts only http:/https: and prepends https:// to scheme-less domains.

Endpoint summary

Public

Session-authenticated

Operator admin

Device

Super admin

HTML routes

Detailed reference

POST /api/devices/enroll

Exchanges an organization's enrollment key for a persistent device bearer token. This is the only moment a workstation proves who it is with a shared secret; afterwards it holds its own token.

Access: public, throttled per source address on failure.

{
  "subdomain": "oakridge",
  "clientId": "PC-01",
  "enrollmentKey": "KEY-ABCD-1234-EFGH",
  "customDomain": "kiosk.oakridge.edu"
}

customDomain is optional; the agent sends it when the workstation was pointed at a custom domain rather than a platform subdomain.

**200 OK**

{
  "status": "ok",
  "deviceToken": "32_byte_hex_bearer_token",
  "clientId": "PC-01",
  "subdomain": "oakridge",
  "organizationName": "Oakridge Holdings",
  "schoolName": "Oakridge Holdings",
  "mode": "portal",
  "targetUrl": "https://oakridge.labkiosk.example.com"
}

schoolName is also sent, with the same value, for agents installed from an ISO older than the organization vocabulary. It is deprecated: new code reads organizationName, and the field will be removed once no workstation in the field depends on it.

The agent writes the token to /etc/labkiosk/config.json with mode 0600. On live media that file lives in the RAM overlay and is lost at power-off, which is intended — the workstation is meant to be installed. On an installed disk, /etc/labkiosk is a mount point for the LABKIOSK_DATA partition, which is what makes a post-install enrolment persist.

Failure modes: an empty or wrong key, an unapproved or suspended organization, or a clientId failing CLIENT_ID_PATTERN are all rejected. Organizations begin with an empty enrollment key, which authenticates nothing until an operator generates one.

GET /api/devices/ws

The workstation's control channel: a WebSocket to its organization's OrgHub. Current agents use it whenever the image has python3-websocket.

Access: Authorization: Bearer <deviceToken> on the upgrade. 401/403 when the token or the organization is refused, 426 without an upgrade.

Close codes: 4001 the workstation was removed, 4003 the organization is not active (both send the screen to re-enrolment), 4000 replaced by a newer connection, 4008 silent for 75 s.

GET /api/console/ws

The Workstations page's live channel. Access: a session with the workstations permission and an Origin of this site. The console sends {"type":"watch", clientIds} for the screens it is showing and receives snapshot, status, frame and removed messages.

POST /api/telemetry

The HTTP heartbeat, called every three seconds by agents without the WebSocket client (and by any agent whose server has no WebSocket route). It carries the same state as the control channel in one request and reply.

Access: Authorization: Bearer <deviceToken>.

Request — exactly these keys; post_telemetry() in agent.py is the reference implementation:

{
  "clientNum": 1,
  "activeUrl": "https://scratch.mit.edu",
  "isLocked": false,
  "thumbnail": "data:image/jpeg;base64,...",
  "vncPassword": "a1b2c3d4"
}

There is **no currentUrl key and no metrics object.** The agent collects no CPU, RAM, or storage statistics; do not build a dashboard against fields that do not exist.

Identity is taken from the token, never the body. Any clientId or tenant the payload claims is discarded.

**200 OK**

{
  "status": "ok",
  "commands": [
    { "id": "cmd-123", "action": "lock", "message": "Eyes to the board please." }
  ],
  "whitelist": ["scratch.mit.edu", "khanacademy.org", "oakridge.labkiosk.example.com"],
  "mode": "portal",
  "targetUrl": "https://oakridge.labkiosk.example.com",
  "broadcastUrl": "",
  "broadcastEpoch": 0
}

**403** if the organization is not active — a suspended organization's workstations stop receiving commands and policy.

POST /api/devices/boot-report

What an installed workstation's last boot did with its system image, as labkiosk-boot-slots check recorded it in /run/labkiosk-update/status.json. The agent sends only the outcomes worth an administrator's attention; the latest is kept on the workstation's row (client_devices.image_version, update_state, update_error, update_state_at). A failure, rollback, fallback or error is also listed in workstation_issues (Settings → Errors & Warnings) as update_failed, update_rolled_back, boot_error (severity error) or boot_fallback (warning). None of it goes to the audit log, which records what people did.

Access: Authorization: Bearer <deviceToken>; the token decides the organization and the workstation.

Request: state (installed | failed | rolled-back | fallback | error), version (the image running), at (when the workstation recorded it, Unix seconds, within the last 7 days); optional previous, failed (release versions) and error (text, cut to 300 characters).

{ "state": "rolled-back", "version": "2.5.1", "failed": "2.6.0", "at": 1791100000 }

**200 OK** → { "status": "ok", "recorded": true }; recorded: false for a report the workstation already sent (or one less than 60 s after the last). **400 malformed, not sent again. 409** the workstation has not checked in yet, sent again later.

GET /api/workstation-issues

Errors and warnings the organization's workstations reported, newest first (?limit=, default 100, at most 200; rows older than 90 days are deleted by the hourly cron).

Access: organization admin or staff with the settings permission.

Each issue carries id, client_id, severity, kind, image_version, details, occurred_at, created_at, report_state (none | pending | sent), report_match (new | existing), and, once sent, issue_url, issue_number, report_status (open | in_progress | pr_open | resolved | closed) and pr_url. The response also carries the organization's opt-in state:

{
  "issues": [ … ],
  "bugReports": {
    "enabled": false,
    "available": true,
    "repository": "owner/repo",
    "termsVersion": "2026-10-04",
    "acceptedTermsVersion": null,
    "termsAcceptedAt": null
  }
}

available is false, and repository null, unless the platform has set up the AI binding, GITHUB_ISSUES_TOKEN and a valid GITHUB_ISSUES_REPO.

POST /api/settings/bug-reports

Opts the organization in to or out of automatic, redacted GitHub bug reports. Turning them on accepts the current Automatic Bug Report Terms (/terms/bug-reports), by version.

Access: organization admin or staff with the settings permission.

{ "enabled": true, "acceptTerms": "2026-10-04" }

{ "enabled": false }

**200 OK** → { "status": "ok", "enabled": true }, with an audit-log row (settings.bug_reports). **400** when enabled is not a boolean, or when turning on without the current terms version. **409** when the platform has not set automatic bug reports up.

POST /api/command

Dispatches a remote action to one workstation or the whole lab.

Access: organization admin.

Supported actions (ALLOWED_COMMANDS in index.ts, mirrored by execute_command() in agent.py):

Anything else is rejected with 400 Unsupported action. There is no broadcast action — a broadcast is navigate to target: "all", which additionally writes broadcast_url and broadcast_epoch onto the tenant row.

{ "targets": ["PC-01", "PC-02"], "action": "lock", "message": "Midterm examination is beginning." }

{ "target": "all", "action": "navigate", "url": "https://scratch.mit.edu" }

{ "target": "all", "action": "navigate", "resetPortal": true }

Targeting supports either targets: string[] (array of clientId strings) or target: string ("all" or a single clientId). Duplicates are dropped, "all" replaces named targets, and at most 500 targets are accepted. When action is lock and no message is supplied, the tenant's default_lock_message is used.

**200 OK** → { "status": "ok", "commandId": "cmd-uuid-99" }

The hub pushes the command to a connected workstation at once; the console sees the new state as soon as the workstation reports it. Every dispatch writes an audit-log row (command.<action>).

GET /api/clients

Returns the organization's fleet: the D1 registry merged with the hub's live status. POST with {"watch": ["PC-01", …]} also asks the hub for those screens' frames for the next 10 seconds -- the fallback for a console without its live channel; thumbnail is present only for watched, online workstations.

Access: organization admin.

{
  "clients": {
    "PC-01": {
      "clientId": "PC-01",
      "clientNum": 1,
      "activeUrl": "https://scratch.mit.edu",
      "isLocked": false,
      "thumbnail": "data:image/jpeg;base64,...",
      "timestamp": 1726300000,
      "lastSeen": "2026-09-14T09:26:40.000Z",
      "online": true,
      "vncPassword": "a1b2c3d4"
    }
  }
}

vncPassword is what makes one-click remote control work without an operator typing anything. It is readable only by an authenticated admin of that specific organization. A remoteHost an older agent still sends is ignored.

POST /api/clients/remove

Decommissions a workstation and revokes its device token. The machine's next heartbeat fails with 401 and it stops appearing on the dashboard.

{ "clientId": "PC-01" }

→ { "status": "ok", "remaining": 14 }

POST /api/auth/register

Creates an organization and its first administrator for review. Ask for emailCode first with POST /api/auth/register/email-code { "email" }. The organization starts pending: nobody is signed in, it cannot sign in or enrol workstations, and the contact is emailed. A super admin confirms the phone number and approves it under Super Admin → Tasks, which emails the console address.

{
  "name": "Oakridge Holdings",
  "legalName": "Oakridge Holdings Pvt Ltd",
  "organizationType": "business",
  "contactName": "Jane Smith",
  "email": "it@oakridge.example",
  "emailCode": "482913",
  "phone": "+91 98765 43210",
  "password": "StrongPassword123!",
  "subdomain": "oakridge",
  "addressLine1": "12 Market Road",
  "city": "Bhubaneswar",
  "region": "Odisha",
  "postalCode": "751001",
  "country": "India",
  "taxId": "21ABCDE1234F1Z5",
  "billingEmail": "accounts@oakridge.example",
  "workstationEstimate": 40,
  "acceptTerms": true
}

→ { "status": "ok", "pending": true, "reference": "LK-7Q2M4K" }

Reserved slugs are refused. Passwords are checked by validatePasswordStrength() and stored as PBKDF2-HMAC-SHA256, 100 000 iterations, 32-byte random salt, 256 derived bits.

POST /api/auth/login

{ "email": "operator@oakridge.edu", "password": "StrongPassword123!" }

→ { "status": "ok", "role": "org_admin", "subdomain": "oakridge", "redirect": "…" }, plus the labkiosk_session and labkiosk_device cookies. An account with two-factor sign-in, on a browser it has not trusted, gets { "status": "two_factor", "challenge": "…" } instead, completed with POST /api/auth/login/verify.

Repeated failures back off exponentially per identifier, tracked in login_attempts.

POST /api/auth/change-password

Rotates the password and revokes the account's other sessions, so a stolen cookie does not survive a password change. This is the only path by which a password changes.

{ "currentPassword": "OldPassword123!", "newPassword": "NewStrongPassword456!" }

GET / POST /api/portal-sites

GET is public and scoped to the host tenant; it is what the User Portal renders from. POST requires organization admin.

{
  "title": "Scratch Programming",
  "url": "https://scratch.mit.edu",
  "category": "Computer Science",
  "icon": "🐱",
  "thumbnailUrl": "https://example.com/scratch.jpg"
}

Adding a card implicitly authorises its host: buildEffectiveWhitelist() unions the permanent allowlist with every portal app domain, so an operator never has to add a site in two places.

POST /api/settings/mode

{ "mode": "single_url", "defaultUrl": "https://canvas.example.edu" }

safeHttpUrl() prepends https:// to a scheme-less domain, so canvas.example.edu is accepted.

POST /api/settings/customization

{
  "name": "Oakridge STEM Academy",
  "defaultLockMessage": "Examination active. No talking.",
  "portalTitle": "Digital Learning Lab",
  "portalSubtitle": "Select an approved page to begin",
  "portalDescription": "Computer Science Lab 304",
  "portalFooter": "For technical assistance, raise your hand."
}

Every one of these strings is attacker-controlled from the platform's perspective and is escaped on render. The test suite asserts that hostile input renders inert.

POST /api/settings/enrollment-key

Rotates the key. Already-enrolled workstations keep their bearer tokens and are unaffected — rotation only prevents new enrolments with the old key.

→ { "status": "ok", "enrollmentKey": "KEY-WXYZ-7890-HIJK" }

Super admin endpoints

All take a tenantId and require a super_admin session.

{ "tenantId": "tenant-uuid-1", "subdomain": "oakridge" }

Suspension is the platform's kill switch: a suspended organization's workstations receive 403 on telemetry, stop getting commands and policy, and its portal stops serving.

Custom domain approval binds an FQDN to a tenant. Once bound, Cloudflare routes it to the worker and resolveTenant() recognises it from the Host header. → Super Admin Guide

The client agent's loopback API

agent.py also serves a small HTTP API on **127.0.0.1:8888**, used only by the local setup wizard. It is not reachable from the network, from the organization LAN, or from a visited web page.

Every request must satisfy both _is_expected_host() (the Host header is loopback) and _is_local_caller() (the Origin, when present, is 127.0.0.1 or localhost). Either check failing returns 403.

One further origin is accepted: the kiosk extension's own origin (chrome-extension://hfjmbeplebjipenkfabncgkpadnjmmoe, pinned by the key in manifest.json). Chromium stamps every non-GET fetch from the extension's service worker with it, and that worker is what the top bar's administrator modal uses to reach POST /api/admin/verify.

POST /api/install takes targetDisk (re-validated against TARGET_DISK_PATTERN) and an optional grubPasswordHash (re-validated against GRUB_PBKDF2_PATTERN). Only a digest is accepted: the wizard derives PBKDF2 in the browser with WebCrypto, so the plaintext boot-menu password never crosses the agent's API, never appears in a process argument, and is never written to disk.

POST /api/network/configure manages NetworkManager connections. On installed machines, connection keyfiles are persisted in LABKIOSK_DATA (/etc/labkiosk/system-connections/) and bind-mounted to /etc/NetworkManager/system-connections by a mount unit in the image (no /etc/fstab is written) so configurations persist across overlayroot="tmpfs" reboots.

→ Client Agent · Disk Installer

Known documentation drift

None currently tracked. docs/API.md was brought back in line with ALLOWED_COMMANDS in src/index.ts (lock, unlock, navigate, reload, reboot, shutdown, clear-session, mute); ALLOWED_COMMANDS and CommandAction in src/types.ts remain the authority.