gRPC

You can use gRPC instead of WebSocket for publishing and subscribing. The service exposes the same logical model: streams and messages keyed by tenant and channel.

Endpoint

Use the gRPC URL (e.g. https://api.example.com:443) with TLS. Your operator will give you the host and port.

Discovery (reflection)

The server supports gRPC reflection. Reflection is a protocol: the server sends the list of services and message types to the client. You do not need a separate doc page; tools like grpcurl, BloomRPC, or Postman can connect and discover the API.

Example with grpcurl (list services):

grpcurl -insecure api.example.com:443 list

To see request/response types for a method:

grpcurl -insecure api.example.com:443 describe api.v1.SomeService.SomeMethod

Authentication

Pass your access token in gRPC metadata (e.g. as a header). The exact metadata key is defined by your operator.

Proto file

The service definition and message types come from the project’s proto file, e.g. common/proto/perimeter.proto. You can open it in the repo or get it from your operator to generate client code. See Reference for the schema.

Error handling

Standard gRPC status codes are used:

• UNAUTHENTICATED (16) — Missing or invalid token.
• PERMISSION_DENIED (7) — Token does not allow the requested tenant/channel.
• UNAVAILABLE (14) — Service down or unreachable; retry with backoff.

See also Error codes.