gRPC API Reference
The Mezite auth service exposes a gRPC API on port 3025.
The protobuf definitions are located at proto/v1/auth.proto.
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. The
full authoritative lists live in
server/auth/grpc_auth.go (unauthenticatedMethods
and adminMethods).
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
ArchiveAuditEvents, the plugin RPCs (ConfigurePlugin, ListPlugins,
SetPluginEnabled), the notification-channel RPCs (CreateNotificationChannel,
ListNotificationChannels,
DisableNotificationChannel,
DeleteNotificationChannel), and
ValidateTOTP. Check the embedded
UnimplementedAuthServiceServer stubs in
proto/v1/auth_grpc.pb.go and the concrete handlers in
server/auth/grpc_handlers.go for the authoritative state.
Proto File
The canonical protobuf definitions live in the repository at proto/v1/auth.proto. Generate Go stubs with:
Generate protobuf stubs bash
make proto