You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page discusses [Codec Server](#codec-server).
24
+
A Codec Server is an HTTP/HTTPS server that you host and operate. It runs your [Payload Codec](/payload-codec) logic to
25
+
encode and decode [Payloads](/dataconversion#payload) on behalf of the Temporal CLI and Web UI. The Codec Server is
26
+
independent of the Temporal Service. Encryption keys and codec logic remain in your environment.
27
+
28
+
For setup instructions, see [Codec Server setup](/production-deployment/data-encryption#codec-server-setup).
29
+
30
+
## Why use a Codec Server
31
+
32
+
When you apply a custom [Payload Codec](/payload-codec) for encryption or compression, data stored in the Temporal
33
+
Service is encoded. The Temporal Service never has access to your encryption keys, so it cannot decode this data.
34
+
Without a Codec Server, the Web UI and CLI display raw encoded payloads.
27
35
28
-
## What is a Codec Server? {#codec-server}
36
+
A Codec Server solves this by giving the Web UI and CLI a way to decode payloads on demand, without exposing keys to the
37
+
Temporal Service. Common reasons to run a Codec Server include:
29
38
30
-
A Codec Server is an HTTP/HTTPS server that uses a [custom Payload Codec](/production-deployment/data-encryption) to decode your data remotely through endpoints.
39
+
-**Debugging Workflows.** View decoded Workflow inputs, outputs, and Event History in the Web UI instead of reading
40
+
base64-encoded or encrypted blobs.
41
+
-**Operating from the CLI.** Use commands like `temporal workflow show` and `temporal workflow execute` with readable
42
+
data, even when payloads are encrypted at rest.
43
+
-**Encoding inputs from the UI and CLI.** When you start or signal a Workflow from the Web UI or CLI, the Codec Server
44
+
can encode the input before it reaches the Temporal Service, so the Temporal Service never sees plaintext (the input
45
+
still travels from your browser or CLI to the Codec Server, which is why HTTPS matters in any non-loopback
46
+
deployment).
47
+
-**Compliance and access control.** Because the Codec Server runs in your environment, you control who can decode
48
+
payloads and under what conditions. You can layer authorization on top of the decode endpoint to restrict access per
49
+
user or per Namespace.
31
50
32
-
{/* This should not have changed with tctl-to-temporal */}
51
+
## How a Codec Server works
52
+
53
+
A Codec Server follows the Temporal
54
+
[Codec Server Protocol](https://github.com/temporalio/samples-go/tree/main/codec-server#codec-server-protocol). It
55
+
exposes two HTTP POST endpoints:
56
+
57
+
-**`/encode`** accepts plaintext payloads and returns encoded payloads. Used for sending payloads.
58
+
-**`/decode`** accepts encoded payloads and returns decoded payloads. Used for retrieving payloads.
59
+
60
+
Both endpoints receive and respond with a JSON body containing a `payloads` array of [Payload](/dataconversion#payload)
61
+
objects. The Codec Server passes each payload through your [Payload Codec](/payload-codec), which applies the same
62
+
encoding or decoding logic that your Workers use.
33
63
34
64
<CaptionedImage
35
-
src="/diagrams/tctl-diagram-codec-server.svg"
36
-
title="Codec Server"
37
-
width="50%"
38
-
zoom="true"
65
+
src="/diagrams/codec-server.svg"
66
+
srcDark="/diagrams/codec-server-dark.svg"
67
+
width="100%"
68
+
title="Codec Server"
39
69
/>
40
70
41
-
A Codec Server follows the Temporal [Codec Server Protocol](https://github.com/temporalio/samples-go/tree/main/codec-server#codec-server-protocol).
42
-
It implements two endpoints:
71
+
When the Web UI or CLI needs to display decoded data, it sends the encoded payloads to your Codec Server's `/decode`
72
+
endpoint. The Codec Server decodes the payloads and returns them to the client. The Temporal Service never sees the
73
+
decoded data.
43
74
44
-
-`/encode`
45
-
-`/decode`
75
+
The `/encode` endpoint works in the other direction. When you start a Workflow or send a Signal from the Web UI or CLI,
76
+
the input is sent to the Codec Server's `/encode` endpoint first, so data reaches the Temporal Service in its encoded
77
+
form.
46
78
47
-
Each endpoint receives and responds with a JSON body that has a `payloads` property with an array of [Payloads](/dataconversion#payload).
48
-
The endpoints run the Payloads through a [Payload Codec](/payload-codec) before returning them.
79
+
Your Codec Server should use the same Payload Codec implementation as your Workers to ensure consistent encoding and
80
+
decoding.
49
81
50
-
Most SDKs provide example Codec Server implementation samples, listed here:
82
+
## Codec Server with External Storage {#external-storage}
The following example walks through how all three endpoints work together:
59
123
60
-
When you apply custom encoding with encryption or compression on your Workflow data, it is stored in the encrypted/compressed format on the Temporal Server. For details on what data is encoded, see [Securing your data](/production-deployment/data-encryption).
124
+
1. A user starts a Workflow from the CLI with a plaintext input. The CLI sends the input to the Codec Server's `/encode`
125
+
endpoint.
126
+
2. The Codec Server encodes the payload through the Payload Codec. The encoded payload exceeds the storage threshold,
127
+
so the Codec Server uploads it to external storage and returns a small reference token.
128
+
3. The CLI sends the reference token to the Temporal Service, which stores it in the Event History.
129
+
4. Later, a user views the Workflow in the Web UI. The Web UI retrieves the Event History from the Temporal Service and
130
+
sends the payloads to the Codec Server's `/decode` endpoint with the `?preserveStorageRefs=true` query parameter.
131
+
5. The Codec Server decodes any non-reference payloads through the Payload Codec, but returns storage references as-is.
132
+
The Web UI displays the reference metadata, indicating the payload is stored externally.
133
+
6. The user clicks to view the full payload. The Web UI sends the storage reference to the `/download` endpoint.
134
+
7. The Codec Server retrieves the encoded payload from external storage, decodes it through the Payload Codec, and
135
+
returns the plaintext result to the Web UI.
61
136
62
-
To see decoded data when using the Temporal CLI or Web UI to perform some operations on a Workflow Execution, configure the Codec Server endpoint in the Web UI and the Temporal CLI.
63
-
When you configure the Codec Server endpoints, the Temporal CLI and Web UI send the encoded data to the Codec Server, and display the decoded data received from the Codec Server.
137
+
## Codec Server vs. Payload Codec
64
138
65
-
For details on creating your Codec Server, see [Codec Server Setup](/production-deployment/data-encryption#codec-server-setup).
139
+
A Codec Server runs a [Payload Codec](/payload-codec) internally, so the two are directly connected. The difference is
|**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. |
145
+
|**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. |
146
+
|**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. |
147
+
|**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. |
148
+
149
+
You implement the transformation logic once in a Payload Codec, then host that logic in a Codec Server so the Web UI and
150
+
CLI can use it remotely.
151
+
152
+
## Securing a Codec Server
153
+
154
+
Because a Codec Server can decode sensitive data, treat it with the same trust as a Worker. Anyone who can call it has
155
+
effective decrypt access. Use HTTPS for any deployment that is not strictly loopback (`localhost`).
156
+
157
+
### Network-level restrictions
158
+
159
+
Restrict network access to the Codec Server. The Web UI can communicate with a Codec Server that is only accessible on
160
+
`localhost`, so running the Codec Server locally is a viable security pattern. For team access, place the Codec Server
161
+
behind a VPN.
162
+
163
+
### Authentication
164
+
165
+
When the Codec Server is accessible beyond `localhost`, authenticate requests to verify the identity of the caller. The
166
+
Web UI supports two approaches:
167
+
168
+
**Include cross-origin credentials (recommended).** Enable **Include cross-origin credentials** in the Web UI Codec
169
+
Server settings. The browser sends cookies scoped to the Codec Server's domain with each request. Your Codec Server must
170
+
have its own authentication mechanism (its own login page and session cookies), so the user must have independently
171
+
authenticated with the Codec Server. This is the recommended approach because the Codec Server maintains its own auth
172
+
boundary, separate from the Temporal UI.
173
+
174
+
**Pass access token.** Enable **Pass access token** in the Web UI Codec Server settings. The Web UI includes the same
175
+
JSON Web Token (JWT) the user used to log into the Temporal UI in the `Authorization` header of each request. Your Codec
176
+
Server validates the token signature against the OpenID Connect (OIDC) provider's JSON Web Key Set (JWKS) endpoint. On
177
+
Temporal Cloud, verify against the
178
+
[Temporal Cloud JWKS endpoint](https://login.tmprl.cloud/.well-known/jwks.json). On a self-hosted Temporal Service, the
179
+
token comes from whatever auth provider you have [configured for the Web UI](/references/web-ui-configuration#auth).
180
+
This approach requires less setup but reuses the same token across the Temporal UI and the Codec Server.
181
+
182
+
### Namespace-level authorization
183
+
184
+
Authentication identifies the caller, but does not confirm the caller is authorized to decode payloads for a specific
185
+
Namespace. Each request from the Web UI includes an `X-Namespace` header identifying the Namespace. To enforce
186
+
Namespace-level access control, your Codec Server must enforce an additional check on whether the authenticated user has
187
+
permissions for the requested Namespace. This applies regardless of which authentication approach you use.
188
+
189
+
### Key management
190
+
191
+
You may also need [key management infrastructure](/key-management) to share encryption keys between your Workers and the
192
+
Codec Server.
193
+
194
+
## SDK Codec Server samples
195
+
196
+
Most Temporal SDKs provide example Codec Server implementations:
0 commit comments