Web API Reference

The Mezite proxy service exposes a REST-style JSON API on port 3080 (HTTPS) under the /v1/webapi/ prefix. This API powers the web UI and supports lightweight integrations.

Authentication

Authenticated endpoints accept either an Authorization: Bearer <session_id> header (used by CLI clients such as msh) or the mezite_session cookie set by the browser SPA after login. Cookie-bearing requests that mutate state are additionally CSRF-protected; Bearer-token requests are exempt from CSRF.

GET /v1/webapi/ping

Unauthenticated. Returns the cluster name, the running server version, and the client-tools version policy this cluster publishes. This is what msh reads to tell a user their binary is behind — see Client Tools. It is also the cheapest way to confirm a proxy is reachable and which cluster answers at an address.

curl https://mezite.example.com:3080/v1/webapi/ping

POST /v1/webapi/login

Authenticate with a local username and password and receive a session ID. The handler also sets a mezite_session cookie (HttpOnly, Secure, SameSite=Strict, 12 hour TTL). It does not return SSH certificates — callers obtain those by following up with the IssueUserCerts gRPC RPC. If the user has WebAuthn enrolled, the endpoint returns 401 with an MFA challenge that must be completed via the /v1/webapi/mfa/webauthn/login/{begin,finish} endpoints before a session is issued.

curl -X POST https://mezite.example.com:3080/v1/webapi/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "secret"}'

GET /v1/webapi/session

Return the caller's current session — username, roles, and expiry. Useful for a client that holds a session ID and wants to know what it is good for without re-authenticating.

POST /v1/webapi/logout

Invalidate the caller's session server-side and clear the mezite_session cookie.

Sessions

GET /v1/webapi/sessions

List recorded SSH sessions. Supports pagination (limit, default 50, max 500, and offset) and filtering by user and protocol. Non-admin callers are restricted to their own recordings server-side; admins see every recording.

curl https://mezite.example.com:3080/v1/webapi/sessions \
  -H "Authorization: Bearer <session_id>"

Nodes

GET /v1/webapi/nodes

List registered SSH nodes with labels and status.

curl https://mezite.example.com:3080/v1/webapi/nodes \
  -H "Authorization: Bearer <session_id>"

Users

GET /v1/webapi/users

List users. Requires admin privileges.

curl https://mezite.example.com:3080/v1/webapi/users \
  -H "Authorization: Bearer <session_id>"

Roles

GET /v1/webapi/roles

List RBAC roles. Requires admin privileges.

curl https://mezite.example.com:3080/v1/webapi/roles \
  -H "Authorization: Bearer <session_id>"

Audit

GET /v1/webapi/audit

Query audit events. Admin only. Supported query parameters: type (event_type exact match), user (user_name exact match), start_time and end_time (RFC 3339 timestamps), limit (default 50, max 500), and offset. Responses are { "items": [...], "total_count": N } with events ordered newest first.

curl "https://mezite.example.com:3080/v1/webapi/audit?type=session.start&start_time=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer <session_id>"

Browser SSH

Status: Available — Browser-based SSH is implemented with xterm.js terminal emulation. Sessions are authenticated via session cookie and use ephemeral SSH certificates.

WebSocket /v1/webapi/ssh/connect

Upgrade an HTTP connection to a WebSocket for interactive SSH. The server authenticates the upgrade request via the same session credential (Bearer header or mezite_session cookie) used for the rest of the web API, issues an ephemeral SSH certificate, and bridges the WebSocket to the target node's SSH session. In practice browsers use the cookie since the WebSocket API cannot set custom auth headers.

Query parameters:

• node — target node hostname (required)
• login — remote login username (default: root)

Example: wss://mezite.example.com:3080/v1/webapi/ssh/connect?node=web1&login=ubuntu

The terminal UI is available at /web/terminal?node=web1&login=ubuntu.

Unauthenticated Endpoints

A few routes are deliberately reachable without a session, because a caller needs them before it has one — or because they publish only public material.