Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/temporal-sa/temporal-cloud-proxy/llms.txt

Use this file to discover all available pages before exploring further.

Workers connect to the proxy on its gRPC port (default 7233) using a standard Temporal SDK client configured with a plain (non-TLS) gRPC connection. The proxy terminates the connection from the worker and establishes its own TLS connection to Temporal Cloud, so workers do not need certificates. Two gRPC metadata headers control routing and authentication on every request.

​
Required gRPC Headers

​
workload-id
string
required
Identifies which workload configuration the proxy should route the request to. Must match a workload_id value defined in the proxy’s YAML config. The proxy returns codes.InvalidArgument if the header is absent, has more than one value, or does not match any configured workload.
​
authorization
string
A Bearer token used to authenticate the worker with the proxy. Format: Bearer <token>. Required when the matched workload has an authentication block configured (JWT or SPIFFE). The proxy returns codes.InvalidArgument if the header is missing when authentication is configured, or codes.Unauthenticated if the token is invalid.

​
Connection Details

SettingValue
Proxy address<proxy-host>:<proxy-port> (default port: 7233)
TLSNot required from the worker — the proxy handles TLS toward Temporal Cloud
Temporal namespaceMust match the namespace configured for the workload in the proxy config
Workers connect to the proxy over a plain gRPC connection. The proxy itself opens a TLS-secured connection to Temporal Cloud using the mTLS certificate or API key configured for each workload.

​
Go SDK Example

The Temporal Go SDK supports injecting custom gRPC interceptors via client.ConnectionOptions. Use a unary client interceptor to append the workload-id and authorization metadata headers to every outgoing call: 
import (
    "context"

    "go.temporal.io/sdk/client"
    "google.golang.org/grpc"
    "google.golang.org/grpc/metadata"
)

// workloadInterceptor returns a gRPC unary interceptor that appends
// the workload-id and authorization headers to every outgoing call.
func workloadInterceptor(workloadID, token string) grpc.UnaryClientInterceptor {
    return func(ctx context.Context, method string, req, reply interface{},
        cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
        ctx = metadata.AppendToOutgoingContext(ctx,
            "workload-id", workloadID,
            "authorization", "Bearer "+token,
        )
        return invoker(ctx, method, req, reply, cc, opts...)
    }
}

// Create a Temporal client that targets the proxy instead of Temporal Cloud directly.
c, err := client.Dial(client.Options{
    HostPort:  "localhost:7233",
    Namespace: "my-namespace.my-account",
    ConnectionOptions: client.ConnectionOptions{
        DialOptions: []grpc.DialOption{
            grpc.WithChainUnaryInterceptor(
                workloadInterceptor("production", jwtToken),
            ),
        },
    },
})
The HostPort points at the proxy rather than <namespace>.<account>.tmprl.cloud:7233. The Namespace field should still be set to the real Temporal Cloud namespace so the SDK includes it in requests.

​
Namespace Configuration

Set the SDK Namespace field to match the namespace value in the proxy’s workload config (e.g. my-namespace.my-account). When API key authentication is in use, the proxy intercepts and overrides the temporal-namespace gRPC header before forwarding the request to Temporal Cloud, ensuring the correct namespace is always sent regardless of what the worker specifies. For mTLS workloads, the namespace value from the incoming metadata is forwarded as-is, so it must match the namespace associated with your mTLS certificate.

​
Example Worker Repositories

The following repositories demonstrate complete worker implementations that connect through Temporal Cloud Proxy:

SPIFFE Worker Example

Uses SPIFFE/SPIRE JWT-SVIDs for proxy authentication. Shows how to obtain a JWT-SVID from the SPIRE agent and pass it as the authorization header.

JWT Worker Example

Uses JWT tokens for proxy authentication. Shows how to acquire a token from an OIDC provider and inject it via a gRPC interceptor.
If worker authentication is not configured for a workload (no authentication block in the proxy config), the authorization header is not required and is ignored by the proxy. You can omit it from the interceptor entirely for unauthenticated workloads.
Each worker request must include exactly one workload-id header. Sending multiple workload-id values or omitting the header entirely causes the proxy to return a codes.InvalidArgument gRPC error and the request will not be forwarded to Temporal Cloud.

Build docs developers (and LLMs) love

Get started for freeTalk to us