Connecting over gRPC
Jennah publishes the API on two endpoints:
| Endpoint | Protocol | Use Case |
|---|---|---|
jennah.alphaus.cloud |
HTTP/JSON | Console, browser sign-in flows, and HTTP clients |
jennah-grpc.alphaus.cloud |
gRPC | SDK and automated integrations, authenticated with an API key or a signed-in session |
Both endpoints route to the same underlying service and share the same authentication and authorization engine. A credential yields identical behavior and access rights regardless of which endpoint is used.
Connect
Using official SDKs
The Python SDK, TypeScript SDK, and Go SDK connect to this endpoint by default, handle credential resolution, and manage token renewal automatically. This page describes connecting directly using generated stubs or command-line tools.
The endpoint uses TLS on port 443. Standard TLS configuration is sufficient; custom certificates or plaintext ports are not required.
import os
import grpc
from jennah.agent.v1 import memory_pb2_grpc
channel = grpc.secure_channel(
"jennah-grpc.alphaus.cloud:443",
grpc.ssl_channel_credentials(),
)
client = memory_pb2_grpc.MemoryServiceStub(channel)
# The credential travels with each call, not with the channel.
token = os.environ["JENNAH_API_KEY"]
metadata = [("authorization", f"Bearer {token}")]
response = client.QueryMemory(request, metadata=metadata)
import (
agentpb "github.com/alphauslabs/jennah-sdk-go/jennah/agent/v1"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials"
)
conn, err := grpc.NewClient("jennah-grpc.alphaus.cloud:443",
grpc.WithTransportCredentials(credentials.NewTLS(nil)))
if err != nil {
return err
}
defer conn.Close()
client := agentpb.NewMemoryServiceClient(conn)
Authenticate
Pass the credential in the authorization metadata header, using the same format as HTTP requests:
The endpoint accepts both API keys (jennah_sk_ prefix) and access tokens generated from sign-in flows. The server identifies the credential type by its prefix and resolves the identity accordingly. Scopes and selectors apply identically across gRPC and HTTP requests.
Attach the credential per call, not per connection
gRPC metadata is sent with each RPC. Use a PerRPCCredentials implementation or set metadata per request rather than expecting connection dialing to persist credentials.
Access tokens obtained via sign-in expire after a fixed duration. When connecting without an SDK, applications must refresh tokens by calling AuthService/RefreshToken with the active refresh token and storing the rotated refresh token returned in the response. Official SDKs manage this refresh cycle and update the shared credentials file automatically.
Endpoint coverage and limitations
All services are available on this endpoint. The gRPC endpoint exposes all registered server operations, subject to standard credential authorization rules.
Enterprise administration tasks (such as inviting members, changing roles, minting keys, or transferring ownership) require a signed-in user access token. API key scopes cannot grant administrative permissions, so requests using an API key will be rejected over gRPC just as they are over HTTP.
Browsers do not support raw gRPC. Web frontends and web applications must use the HTTP endpoint.
The jnh CLI uses HTTP. It is built using the published protobuf messages available to external integrators, ensuring CLI operations mirror standard public HTTP integration pathways.
Sign-in flows require HTTP. Although login and device-code RPCs exist in the protobuf definitions, authentication flows rely on browser redirects and cookies managed by the HTTP endpoint. Use the HTTP endpoint to authenticate, then use gRPC with the resulting credential.