Read payloads in Temporal UI

For: cluster operators.

Point Temporal's UI at the edge's codec when you need to inspect encrypted payloads.

Temporal's UIs: the codec endpoint

Temporal's UI shows ciphertext until it is given a codec server. The edge serves one at https://<edge>:7443/codec.

Temporal Cloud UI. In the namespace's settings, under Codec Server:

1. Endpoint: https://<edge address>:7443/codec. It must be reachable from your browser, not from the internet, and its certificate must be one your browser trusts: put the edge behind a load balancer with your own certificate, or add its address with --san.
2. Turn on Pass the user access token. Leave Include cross-origin credentials off: the edge never reads cookies.
3. Link each person's Temporal Cloud email to their account: oz0 user link-temporal-cloud kim [email protected].

The edge checks the access token's signature against Temporal Cloud's keys, finds the account linked to its email, and decodes only for accounts with the content permission on the tenant. Encoding (when the UI sends a signal) also needs the operator role. Every decode and encode is in the audit log as payload.decode or payload.encode, and every refusal of a signed-in person as payload.decode.refused or payload.encode.refused; requests without a valid token are only logged. Only https://cloud.temporal.io may call it from a browser; add other origins with --codec-allow-origin.

The Temporal Cloud UI sends the same access token to the codec server of every namespace a person browses, including other organizations' namespaces, whose codec servers could send it on to your edge. So the edge takes access tokens only when they are bound to your cluster.

With Temporal Cloud's keys the binding is --codec-account-claim: the name of a claim that must hold your --temporal-cloud-account. An audience binds only when it names your cluster alone, and a token for any Temporal Cloud account can carry the same one, so with Temporal Cloud's keys --codec-jwt-audience is checked when set but does not count as a binding.

With an identity provider's own keys (--codec-jwks-url), an audience that provider issues for your codec endpoint alone binds them.

Until the tokens are bound, the edge takes none (operators' certificates and tenant API keys still decode), says so at start, and the encryption status shows the codec endpoint as closed.

Which claims Temporal Cloud's tokens carry is not documented yet, so check one of your tokens for a claim that names your account before you set it.

--codec-jwt-unbound takes any unexpired token of a linked user that nothing binds, as earlier versions did, knowing that another codec server could replay one here; the edge warns at start.

Either way, a token is taken for at most --codec-jwt-max-age (default 12 hours) after it was issued.

A token's address must be verified: its email_verified claim must say true (the JSON boolean, or the string "true" some providers send, as at sign-in); any other value is refused. Temporal Cloud's own tokens name the Temporal Cloud user by the address they were invited with and are not documented to carry the claim, so with Temporal Cloud's keys a token without it is taken.

With an identity provider's own keys, a token without the claim is refused unless you set --codec-assume-email-verified, for a provider that verifies or sets every address itself (such as Microsoft Entra ID, as sign-in's --assume-email-verified).

Temporal's own UI and CLI against an external cluster. The Temporal CLI decodes with a tenant API key (one of the whole tenant: a key scoped to some agents is refused, since the codec decodes any job's payloads):

temporal workflow show --workflow-id job-123 --namespace default \
  --codec-endpoint https://edge.internal:7443/codec --codec-auth "Bearer $OZ0_API_KEY"

For a self-hosted Temporal UI against an external cluster (its own deployment, not the one the console embeds), set its codec endpoint to the edge, TEMPORAL_CODEC_ENDPOINT=https://<edge>:7443/codec with TEMPORAL_CODEC_PASS_ACCESS_TOKEN=true, and point --codec-jwks-url, --codec-jwt-issuer (required with --codec-jwks-url), --codec-email-claim and --codec-jwt-audience (an audience the provider issues for this codec endpoint alone) at the identity provider whose tokens it passes, with --codec-assume-email-verified if its tokens carry no email_verified claim. Without a codec endpoint that UI shows ciphertext, which, now that a cluster encrypts by default, is what it shows for every job.

The console. On Temporal Cloud the embedded Temporal UI is not served (/temporal/ says why); each job's page links to its workflow in the Temporal Cloud UI instead, and the overview shows the backend. With an embedded or external backend, the embedded Temporal UI at /temporal/ decodes payloads with its own codec on the management port, for the admin signed in: see Temporal's UI.