gRPC API Reference

The Mezite auth service exposes a gRPC API on port 3025, as the single service mezite.v1.AuthService. It is an internal control-plane API — it should not be published to the internet, and the proxy's Web API is the surface intended for lightweight integrations.

Authentication and Authorization

Most RPCs require an authenticated caller. Callers present a session ID issued by AuthenticateLocal (or one of the SSO flows exposed by the web API) as authorization: Bearer <session_id> gRPC metadata. Examples of unauthenticated RPCs include RegisterAgent, DeregisterAgent, AgentHeartbeat, GenerateHostCerts, ValidateJoinToken, RegisterUsingIAMMethod, Ping, AuthenticateLocal, BeginWebAuthnLogin, FinishWebAuthnLogin, BootstrapAgentIdentity, RenewAgentIdentity, and AuthenticateSPIFFE — each carries its own credential (join token, signed STS challenge, WebAuthn assertion, etc.). Mutating operations on users, roles, tokens, locks, connectors, agent identities, cluster-config, trusted clusters, and CA rotation require the caller's session to have the admin role; read RPCs on users and roles (GetUser, ListUsers, GetRole, ListRoles) are reachable by any authenticated caller.

Authentication RPCs

RPC	Description
`AuthenticateLocal`	Exchange a username and password for a session ID. This RPC validates the password only — WebAuthn step-up is enforced by the web endpoint `POST /v1/webapi/login`, not by this gRPC handler.
`IssueUserCerts`	Issue short-lived SSH user certificates (and the trusted host CA bundle) for an authenticated user.
`ChangePassword`	Change the authenticated user's local password.

Agent and Node RPCs

RPC	Description
`RegisterAgent`	Commit a new agent (SSH node) into the cluster registry using a join token. Returns the assigned `agent_id` and `cluster_name`. Host SSH/x509 certs are issued separately by `GenerateHostCerts`, which the agent calls before `RegisterAgent`.
`RegisterUsingIAMMethod`	Bidirectional streaming join flow for nodes attesting via an AWS STS sts:GetCallerIdentity challenge.
`AgentHeartbeat`	Periodic keepalive sent by agents to report node health.
`DeregisterAgent`	Remove an agent from the cluster.
`ListNodes`	List registered SSH nodes and their metadata.
`UpdateNode`	Update a registered node's labels.
`GenerateHostCerts`	Issue host SSH certificates for an agent given a valid join token.

User and Role RPCs

RPC	Description
`GetUser`	Retrieve a user by name.
`ListUsers`	List all local users.
`CreateUser`	Create a new local user with assigned roles. Admin only.
`UpdateUser`	Update a user (roles, traits, etc.). Admin only.
`DeleteUser`	Delete a user from the cluster. Admin only.
`CreateRole` / `UpdateRole` / `DeleteRole`	Manage RBAC roles. Admin only.
`GetRole` / `ListRoles`	Read RBAC roles.

Session and Audit RPCs

RPC	Description
`ListSessionRecordings`	List recorded SSH sessions with filtering and pagination.
`GetSessionRecording`	Fetch a single session recording by ID.
`StreamSessionRecording`	Client-streaming RPC used by agents to upload a session recording in chunks.
`UploadSessionRecording`	Unary fallback used by agents to upload a small recording in a single request.
`ListActiveSessions`	List sessions that are currently active across the cluster.
`RevokeSession`	Revoke an active user session by ID (created by either `AuthenticateLocal` or the web login). Admin only.
`EmitAuditEvent`	Write an audit event to the log (used by agents and the proxy).
`QueryAuditEvents`	Query audit events by type, user, time range, etc.

Access Request RPCs

RPC	Description
`CreateAccessRequest`	Submit a request for elevated roles or node access.
`GetAccessRequest`	Fetch a single access request by ID.
`ListAccessRequests`	List access requests with optional status filtering.
`ReviewAccessRequest`	Approve or deny a pending access request.
`CancelAccessRequest`	Cancel an access request the caller owns.

Unimplemented stubs

A handful of RPCs are declared in auth.proto but currently return codes.Unimplemented — they are reserved for upcoming features and should not be relied on. As of this writing the unimplemented set is the plugin RPCs (ConfigurePlugin, ListPlugins, SetPluginEnabled), the notification-channel RPCs (CreateNotificationChannel, ListNotificationChannels, DisableNotificationChannel, DeleteNotificationChannel), and ValidateTOTP. They return Unimplemented rather than failing in some subtler way, so a caller finds out immediately.

For long-term audit archive, use the S3 audit-export sink (audit_export.* on the Configuration page).

Service Name

All RPCs above live on a single service, mezite.v1.AuthService. Fully-qualified method paths therefore take the form /mezite.v1.AuthService/<Rpc> — which is also how they appear in the interceptor's method lists and in audit and access logs.

Server reflection is not enabled on the listener, so a generic client such as grpcurl needs the descriptors supplied explicitly. If you are building an integration against this API and need the .proto definitions, contact us.