Encryption
Workflow SDK automatically encrypts user data in the event log without requiring code changes. To start using workflows, see the getting started guide for your framework.
Workflow SDK supports automatic end-to-end encryption of all user data before writing it to the event log. When a World implementation provides encryption support, you can pass sensitive data, such as API keys, tokens, or user credentials, as workflow inputs, step arguments, and return values. The storage backend only sees ciphertext.
Encryption support varies by World implementation. See the Worlds page to check which Worlds support this feature. World implementations opt into encryption by providing a getEncryptionKeyForRun() method. The core runtime uses it automatically when present.
What is encrypted
All user data flowing through the event log is encrypted:
- Workflow inputs: Arguments passed when starting a workflow
- Workflow return values: The final output of a workflow
- Step inputs: Arguments passed to step functions
- Step return values: The result returned by step functions
- Hook metadata: Data attached when creating a hook
- Hook payloads: Data received by hooks and webhooks
- Stream data: Each frame in a
ReadableStreamorWritableStream
Metadata such as workflow names, step names, entity IDs, timestamps, and lifecycle states are not encrypted. This allows the observability tools to display run structure and timelines without requiring decryption.
How it works
Compression
Payloads are compressed before encryption. A format prefix on the stored value records the compression codec, and the inner payload keeps its own serialization format prefix after decompression. Repetitive payloads compress heavily. AI token streams average around 80% smaller, reducing storage and network transfer. Like encryption, compression is automatic and requires no code changes.
The codec is zstd when both the writer and the run's deployment run Node.js 22.15+ (or 23.8+), and gzip otherwise. Runs started on an older Node.js version stay readable after you upgrade the project's Node.js version. To force a codec, set WORKFLOW_COMPRESSION_CODEC.
Key management
Each workflow run is encrypted with its own unique key, provided by the World implementation via getEncryptionKeyForRun(). How the key is generated and stored is up to the World.
For example, the Vercel World provides unique keys per run and execution environment, ensuring that a given run can only decrypt data from that run itself.
Encryption algorithm
Data is encrypted using AES-256-GCM via the Web Crypto API:
- A random 12-byte nonce is generated for each encryption operation
- The GCM authentication tag provides integrity verification and detects any ciphertext tampering
- The same plaintext produces different ciphertext each time due to the random nonce
Decrypting data
When viewing workflow runs through the observability tools, encrypted fields display as locked placeholders until you explicitly choose to decrypt them.
Permissions
The World implementation controls decryption access. On Vercel, decryption follows the same permissions model as project environment variables. If you don't have permission to view environment variable values for a project, you can't decrypt its workflow data. Vercel records each decryption request in your Vercel audit log, so your team can see when someone accessed workflow data and who accessed it.
Web dashboard
Click the Decrypt button in the run detail panel to decrypt all data fields. Decryption happens entirely in the browser through the Web Crypto API. The observability server retrieves the encryption key but never sees your plaintext data.
CLI
Add the --decrypt flag to any inspect command:
Without --decrypt, encrypted fields display as 🔒 Encrypted placeholders.
Custom World implementations
The core runtime encrypts data automatically when the World implementation provides a getEncryptionKeyForRun() method. The core runtime can call this method in two forms:
Use getEncryptionKeyForRun(run) when the runtime already holds the run entity. Use getEncryptionKeyForRun(runId, context?) everywhere else: in paths like start() where the run does not exist yet, and in paths that have a run id but no reason to load the run's payloads, such as resolving the key for a stream read. Either way context carries whatever the World needs to find the key, such as deploymentId.
To add encryption support to a custom World:
- Implement
getEncryptionKeyForRun()on yourWorldclass, handling both call shapes - Return the raw 32-byte key as a
Uint8Array. The core runtime uses it for AES-256-GCM operations - Ensure the same key is returned for the same run ID across invocations (for decryption during replay)
The Vercel World implementation uses HKDF derivation from a deployment-scoped key, but any consistent key management scheme will work.