Skip to main content

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 show and temporal workflow execute with 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 sensitive data is never sent in plaintext.
  • 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:

  • /encode accepts plaintext payloads and returns encoded payloads.
  • /decode accepts encoded payloads and returns decoded 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

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. Decoding happens entirely on the client side. 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 vs. Payload Codec​

Because both use the word "Codec," it is easy to confuse a Codec Server with a Payload Codec. They serve different purposes:

Payload CodecCodec Server
What it isA component in your Data Converter that transforms Payloads (bytes to bytes).An HTTP server that exposes your Payload Codec over the network.
Where it runsIn-process, inside your Workers and Clients.As a standalone HTTP service in your environment.
Who calls itThe Temporal SDK calls it automatically during serialization and deserialization.The Web UI and CLI call it over HTTP to encode or decode Payloads on demand.
PurposeApplies encryption, compression, or other transformations to all Payloads that pass through the Data Converter.Gives the Web UI and CLI access to those same transformations without bundling your codec logic into every tool.

A Codec Server wraps a Payload Codec. 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.

Authorization​

Access to a Codec Server should be restricted because it can decode sensitive data with a single API call. Common approaches include:

  • Network-level restrictions. Run the Codec Server on localhost or behind a VPN. The Web UI can communicate with a Codec Server that is only accessible locally.
  • Token-based authorization. Integrate your organization's authentication provider (OAuth, Auth0, or similar). Temporal Cloud can pass access tokens (JWT) to your Codec Server with each request. Verify these tokens against the Temporal Cloud JWKS endpoint.

You may also need a 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: