Codec Server
A Codec Server is an HTTP/HTTPS server that you host and operate. It runs your Payload Codec logic to encode and decode Payloads on behalf of the Temporal CLI and Web UI. The Codec Server is independent of the Temporal Service. Encryption keys and codec logic remain in your environment.
For setup instructions, see Codec Server setup.
Why use a Codec Server
When you apply a custom Payload Codec for encryption or compression, data stored in the Temporal Service is encoded. The Temporal Service never has access to your encryption keys, so it cannot decode this data. Without a Codec Server, the Web UI and CLI display raw encoded payloads.
A Codec Server solves this by giving the Web UI and CLI a way to decode payloads on demand, without exposing keys to the Temporal Service. Common reasons to run a Codec Server include:
- Debugging Workflows. View decoded Workflow inputs, outputs, and Event History in the Web UI instead of reading base64-encoded or encrypted blobs.
- Operating from the CLI. Use commands like
temporal workflow showandtemporal workflow executewith readable data, even when payloads are encrypted at rest. - Encoding inputs from the UI and CLI. When you start or signal a Workflow from the Web UI or CLI, the Codec Server can encode the input before it reaches the Temporal Service, so the Temporal Service never sees plaintext (the input still travels from your browser or CLI to the Codec Server, which is why HTTPS matters in any non-loopback deployment).
- Compliance and access control. Because the Codec Server runs in your environment, you control who can decode payloads and under what conditions. You can layer authorization on top of the decode endpoint to restrict access per user or per Namespace.
How a Codec Server works
A Codec Server follows the Temporal Codec Server Protocol. It exposes two HTTP POST endpoints:
/encodeaccepts plaintext payloads and returns encoded payloads. Used for sending payloads./decodeaccepts encoded payloads and returns decoded payloads. Used for retrieving payloads.
Both endpoints receive and respond with a JSON body containing a payloads array of Payload
objects. The Codec Server passes each payload through your Payload Codec, which applies the same
encoding or decoding logic that your Workers use.
Codec Server
When the Web UI or CLI needs to display decoded data, it sends the encoded payloads to your Codec Server's /decode
endpoint. The Codec Server decodes the payloads and returns them to the client. The Temporal Service never sees the
decoded data.
The /encode endpoint works in the other direction. When you start a Workflow or send a Signal from the Web UI or CLI,
the input is sent to the Codec Server's /encode endpoint first, so data reaches the Temporal Service in its encoded
form.
Your Codec Server should use the same Payload Codec implementation as your Workers to ensure consistent encoding and decoding.
Codec Server with External Storage
When your Workers and Clients use External Storage, your storage drivers replace some payloads in the Event History with small references that point to data in an external store like Amazon S3. The Temporal Service and the Web UI only see these references, not the actual payload data. This is further complicated by setups where you run Codecs in proxy that encode payloads after the Data Converter has returned on the Worker. Your Codec Server must be able to handle downloading and decoding in the correct order for you to be able to view the Workflow data in the UI or CLI.
To support External Storage, create a handler using NewPayloadHTTPHandler with PayloadHTTPHandlerOptions. The options
accept your storage drivers, your pre-storage codecs (the Payload Codecs configured in your Worker's Data Converter),
and any post-storage codecs (codecs applied by a proxy after external storage). The handler applies them in the correct
order across all endpoints automatically. When you configure the handler with storage drivers, the existing endpoints
become storage-aware and a new /download endpoint becomes available:
NewPayloadHTTPHandler runs the full encode-store-encode and decode-retrieve-decode pipeline. Do not use it as a target
for a remote Data Converter or remote codec on your Workers. For remote codecs, use NewPayloadCodecHTTPHandler
separately. If you need both, set up NewPayloadHTTPHandler for the Web UI and CLI alongside
NewPayloadCodecHTTPHandler for your Workers, and configure both with the same codecs.
/downloadretrieves the actual payload data from external storage and decodes it through the Payload Codec. This endpoint is used internally by/decodewhen it encounters storage references, but you can also call it directly from the Web UI to retrieve the decoded payload. The Temporal Web UI uses this endpoint when you click to view the full payload for a storage reference./decodestill decodes encoded payloads, but also handles storage references. By default,/decodeuses the download logic internally to retrieve and decode any storage references in the request alongside regular payloads. With the?preserveStorageRefs=truequery parameter,/decodeskips retrieval and returns storage references as-is./encodeapplies the Payload Codec, then uploads payloads that exceed the size threshold to external storage and replaces them with reference tokens.
Codec Server with External Storage
The following example walks through how all three endpoints work together:
- A user starts a Workflow from the CLI with a plaintext input. The CLI sends the input to the Codec Server's
/encodeendpoint. - The Codec Server encodes the payload through the Payload Codec. The encoded payload exceeds the storage threshold, so the Codec Server uploads it to external storage and returns a small reference token.
- The CLI sends the reference token to the Temporal Service, which stores it in the Event History.
- Later, a user views the Workflow in the Web UI. The Web UI retrieves the Event History from the Temporal Service and
sends the payloads to the Codec Server's
/decodeendpoint with the?preserveStorageRefs=truequery parameter. - The Codec Server decodes any non-reference payloads through the Payload Codec, but returns storage references as-is. The Web UI displays the reference metadata, indicating the payload is stored externally.
- The user clicks to view the full payload. The Web UI sends the storage reference to the
/downloadendpoint. - The Codec Server retrieves the encoded payload from external storage, decodes it through the Payload Codec, and returns the plaintext result to the Web UI.
Codec Server vs. Payload Codec
A Codec Server runs a Payload Codec internally, so the two are directly connected. The difference is where the codec logic runs and who calls it.
| Payload Codec | Codec Server | |
|---|---|---|
| Purpose | Encodes and decodes Payloads. Applies encryption, compression, or other byte-level transformations. | Hosts a Payload Codec as an HTTP service so the Web UI and CLI can encode and decode Payloads remotely. |
| Runs where | In-process, inside your Workers and Clients. Also runs inside the Codec Server. | As a standalone HTTP service in your environment, with a Payload Codec inside it. |
| Called by | The Temporal SDK, automatically on every serialization and deserialization. | The Web UI and CLI, over HTTP, when a user views or submits Payload data. |
| Has access to encryption keys | Yes. Keys are available in the Worker or Client process. | Yes. Must be configured with the same keys the Payload Codec uses. |
You implement the transformation logic once in a Payload Codec, then host that logic in a Codec Server so the Web UI and CLI can use it remotely.
Securing a Codec Server
Because a Codec Server can decode sensitive data, treat it with the same trust as a Worker. Anyone who can call it has
effective decrypt access. Use HTTPS for any deployment that is not strictly loopback (localhost).
Network-level restrictions
Restrict network access to the Codec Server. The Web UI can communicate with a Codec Server that is only accessible on
localhost, so running the Codec Server locally is a viable security pattern. For team access, place the Codec Server
behind a VPN.
Authentication
When the Codec Server is accessible beyond localhost, authenticate requests to verify the identity of the caller. The
Web UI supports two approaches:
Include cross-origin credentials (recommended). Enable Include cross-origin credentials in the Web UI Codec Server settings. The browser sends cookies scoped to the Codec Server's domain with each request. Your Codec Server must have its own authentication mechanism (its own login page and session cookies), so the user must have independently authenticated with the Codec Server. This is the recommended approach because the Codec Server maintains its own auth boundary, separate from the Temporal UI.
Pass access token. Enable Pass access token in the Web UI Codec Server settings. The Web UI includes the same
JSON Web Token (JWT) the user used to log into the Temporal UI in the Authorization header of each request. Your Codec
Server validates the token signature against the OpenID Connect (OIDC) provider's JSON Web Key Set (JWKS) endpoint. On
Temporal Cloud, verify against the
Temporal Cloud JWKS endpoint. On a self-hosted Temporal Service, the
token comes from whatever auth provider you have configured for the Web UI.
This approach requires less setup but reuses the same token across the Temporal UI and the Codec Server.
Namespace-level authorization
Authentication identifies the caller, but does not confirm the caller is authorized to decode payloads for a specific
Namespace. Each request from the Web UI includes an X-Namespace header identifying the Namespace. To enforce
Namespace-level access control, your Codec Server must enforce an additional check on whether the authenticated user has
permissions for the requested Namespace. This applies regardless of which authentication approach you use.
Key management
You may also need key management infrastructure to share encryption keys between your Workers and the Codec Server.
SDK Codec Server samples
Most Temporal SDKs provide example Codec Server implementations: