API Reference

Mezite exposes two API surfaces for programmatic access to the SSH platform.

gRPC API (Auth Service)

The auth service listens on port 3025 and exposes a gRPC API defined in proto/v1/auth.proto. This is the primary API used by all Mezite components (agents, CLI tools, and the web UI) to authenticate, manage resources, and emit audit events.

See the gRPC API reference for the full list of RPCs.

Web / REST API (Proxy Service)

The proxy service listens on port 3080 (HTTPS) and provides a REST-style JSON API under /v1/webapi/. This API powers the web UI and can be used for lightweight integrations that do not require a gRPC client.

See the Web API reference for available endpoints.

Authentication

Both APIs are session-based. Call AuthenticateLocal over gRPC, or POST /v1/webapi/login over HTTPS, to exchange a username and password for a session ID. The web endpoint also sets a mezite_session cookie used by the browser SPA; CLI clients pass the same session ID in an Authorization: Bearer <session_id> header. Once authenticated, call IssueUserCerts over gRPC to receive short-lived SSH certificates for subsequent SSH connections.

The gRPC listener requires TLS 1.3 in production and presents a host-CA-issued server certificate. Client certificates are accepted when presented but the listener does not reject connections that omit them, because a small set of join/register RPCs is reachable before a client has a certificate at all. Authentication and authorization are enforced per-RPC by the gRPC auth interceptor based on a session bearer token (Authorization: Bearer <session_id>) or, for agent calls, an x-agent-id metadata header — see server/auth/grpc_auth.go for the unauthenticated and admin-only method lists.

Three distinct join / auth flows

The gRPC surface exposes three flows that look superficially similar but do different things — keep them straight when calling the API programmatically:

  • RegisterAgent / RegisterUsingIAMMethod — Node-join flow. mezd calls this once on a new machine to exchange a one-time bootstrap token (or an AWS STS get-caller-identity proof, for IAM joins) for a host certificate and the long-lived registration material it uses on subsequent restarts.
  • Bot / agent-identity bootstrap — Issued through mezctl agent-identities add, which provisions a one-time bootstrap token tied to an agent identity. The bot redeems the token by calling BootstrapAgentIdentity on the auth service to obtain its first SSH and X.509 credentials plus a renewal token, then uses RenewAgentIdentity to rotate credentials before they expire. This is a separate flow from RegisterUsingIAMMethod — it does not currently support IAM-based join.
  • AuthenticateSPIFFE — Workload-identity SSH auth. A workload on a registered node presents its SPIFFE SVID and receives a short-lived SSH certificate scoped to the workload role encoded in the SVID URI SAN. This is not a node-join or bot-bootstrap flow; it assumes the workload already holds a valid SVID issued by the SPIFFE CA.