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.

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"}'

Sessions

GET /v1/webapi/sessions

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

List sessions bash

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.

List nodes bash

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

Users

GET /v1/webapi/users

List users. Requires admin privileges.

List users bash

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.

List roles bash

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.

Query audit events bash

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.