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.

A workload is the central configuration unit in the Temporal Cloud Proxy. Each workload entry maps a workload_id string — supplied by workers in the workload-id gRPC metadata header — to a specific Temporal Cloud namespace, along with the credentials the proxy uses to reach that namespace and any optional payload encryption or worker authentication policy. A single proxy instance can serve any number of workloads simultaneously, each with independent settings.

​
Field reference

​
workload_id
string
required
A unique string identifier for this workload. Workers must set the workload-id gRPC metadata header to this value on every request. The proxy uses this header to look up the matching configuration and route the call to the correct Temporal Cloud namespace. Any non-empty string is valid, but values must be unique across all workload entries in the file.
​
temporal_cloud.namespace
string
required
The fully qualified Temporal Cloud namespace in <namespace>.<account> format, for example my-namespace.my-account. This value is injected into every outbound call as the temporal-namespace gRPC metadata header when using API key authentication.
​
temporal_cloud.host_port
string
required
The gRPC endpoint address the proxy dials when forwarding calls for this workload.
  • mTLS: use <namespace>.<account>.tmprl.cloud:7233
  • API key: use <region>.<cloud>.api.temporal.io:7233 (e.g. us-east-1.aws.api.temporal.io:7233)
​
temporal_cloud.authentication
object
required
Credentials the proxy uses to authenticate with Temporal Cloud. Supports mTLS certificate pairs or API keys. See the Namespace Auth page for the complete reference.
​
encryption
object
Optional. Payload encryption settings. When present, the proxy encrypts outgoing payloads and decrypts incoming encrypted payloads using AES-GCM with a KMS-managed data key. Workers communicate in plaintext; encryption is entirely transparent to them. Supports aws-kms and gcp-kms providers. See the Encryption page for the complete reference.
​
authentication
object
Optional. Worker-to-proxy authentication settings. When present, every inbound request must include a valid authorization: Bearer <token> gRPC metadata header. The proxy validates the token before forwarding the call. Supports jwt and spiffe authenticator types. See the Worker Auth page for the complete reference.

​
Example: two workloads

The following example configures two workloads on a single proxy instance — one production workload using an API key and AWS KMS encryption, and one staging workload using mTLS without encryption. 
workloads:
  - workload_id: "production"
    temporal_cloud:
      namespace: "prod.mycompany"
      host_port: "us-east-1.aws.api.temporal.io:7233"
      authentication:
        api_key:
          env: PROD_TEMPORAL_API_KEY
    encryption:
      type: "aws-kms"
      config:
        key-id: "arn:aws:kms:us-east-1:123456789012:key/abc123"

  - workload_id: "staging"
    temporal_cloud:
      namespace: "staging.mycompany"
      host_port: "staging.mycompany.tmprl.cloud:7233"
      authentication:
        tls:
          cert_file: "/certs/staging.crt"
          key_file: "/certs/staging.key"
Workers targeting the production namespace set workload-id: production in their gRPC metadata. Workers targeting staging set workload-id: staging. The proxy routes each call independently.
Each workload_id must be unique across the entire config file. Starting the proxy with duplicate IDs causes a startup error: workload already exists: <id>. The process exits immediately and does not serve any traffic until the configuration is corrected.

​
Passthrough mode

If neither encryption nor authentication is set on a workload, the proxy operates in passthrough mode for that workload: calls are forwarded to Temporal Cloud using only the namespace-level credentials (tls or api_key), with no payload encryption and no worker token validation. This is useful for initial integration testing or scenarios where workers themselves handle API key injection. However, the proxy logs a startup warning for each workload configured in passthrough mode: 
WARN  workload configured without worker authentication  {"workload-id": "staging"}
WARN  workload configured without payload encryption     {"workload-id": "staging"}
Review these warnings before deploying to production to ensure the absence of encryption and authentication is intentional.

Build docs developers (and LLMs) love

Get started for freeTalk to us