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.

Each workload needs credentials to authenticate with Temporal Cloud. The proxy supports two authentication methods: mTLS (client certificate and private key) and API key. Both methods are configured under temporal_cloud.authentication in the workload block. Only one method can be active per workload — the proxy rejects configurations that specify both.
You cannot configure both tls and api_key on the same workload. If both are present, the proxy exits at startup with the error: cannot have both api key and mtls authentication configured on a single workload: <workload_id>.

​
mTLS authentication

The proxy loads a PEM-encoded client certificate and private key from local files, then presents them during the TLS handshake with Temporal Cloud. This is the authentication method used with tmprl.cloud:7233 endpoints. 
temporal_cloud:
  namespace: "my-namespace.my-account"
  host_port: "my-namespace.my-account.tmprl.cloud:7233"
  authentication:
    tls:
      cert_file: "/path/to/client.crt"
      key_file: "/path/to/client.key"
​
temporal_cloud.authentication.tls.cert_file
string
required
Absolute or relative path to the PEM-encoded client certificate file. The file must be readable by the process running the proxy at startup — the certificate is loaded once during initialisation using tls.LoadX509KeyPair.
​
temporal_cloud.authentication.tls.key_file
string
required
Absolute or relative path to the PEM-encoded private key file corresponding to the certificate. Must be readable by the proxy process at startup.
Obtain mTLS certificates from the Temporal Cloud UI under your namespace’s Certificate Filters section. Download the client certificate and key, save them as PEM files on the host running the proxy, and reference those paths in the config.

​
API key authentication

When an API key is configured, the proxy strips the incoming authorization and temporal-namespace metadata headers and replaces them with its own on every outbound call:
  • authorization: Bearer <key>
  • temporal-namespace: <namespace>
This method is used with api.temporal.io:7233 endpoints. The API key can be provided as a literal inline value or read from an environment variable at startup: 
# Inline value (not recommended for production)
temporal_cloud:
  authentication:
    api_key:
      value: "your-api-key-here"

# Read from environment variable (recommended)
temporal_cloud:
  authentication:
    api_key:
      env: TEMPORAL_API_KEY
​
temporal_cloud.authentication.api_key.value
string
The literal API key string. If set, the key is read directly from the config file. Avoid using this in production — prefer env to keep credentials out of config files that may be stored in version control.
​
temporal_cloud.authentication.api_key.env
string
The name of an environment variable whose value is the API key. The proxy reads the variable once at startup when building the connection. If the variable is not set or is empty, the proxy returns an error: no api key provided.
If both value and env are set on the same api_key block, value takes precedence and the proxy logs a warning at startup: both value and envvar provider for api key; using value.
Use the env field in production environments. Set the environment variable before starting the proxy — for example, inject it from a secrets manager or Kubernetes secret into the proxy container’s environment at runtime, keeping the credential entirely out of the config file.

​
Passthrough mode

If neither tls nor api_key is set under temporal_cloud.authentication, the proxy forwards calls without adding any authentication credentials. This is useful when the calling worker injects the API key directly into its gRPC metadata, so the proxy simply passes that header through unchanged. Note that passthrough mode does not support mTLS — the TLS handshake with Temporal Cloud uses an empty certificate list, which is only compatible with API key–based endpoints (api.temporal.io:7233).

Build docs developers (and LLMs) love

Get started for freeTalk to us