Skip to main content
Built-in AES encryption is the recommended approach for encrypting Agent Server data at rest. Use custom encryption handlers only when you need per-tenant keys or an external key management system.

​
Configure AES encryption

Set LANGGRAPH_AES_KEY to encrypt checkpoint blobs automatically:
  1. Add pycryptodome to your dependencies in langgraph.json:
  2. Set LANGGRAPH_AES_KEY to a 16, 24, or 32-byte key for AES-128, AES-192, or AES-256, respectively.

​
Encrypt JSON fields

Set LANGGRAPH_AES_JSON_KEYS to a comma-separated list of JSON keys to encrypt:
These keys are encrypted wherever they appear in thread, assistant, run, cron, and store data.
Encrypted fields cannot be searched or filtered.
System fields cannot be encrypted: langgraph_version, langgraph_api_version, langgraph_plan, langgraph_host, langgraph_api_url, langgraph_request_id, langgraph_auth_user_id, and langgraph_auth_permissions.

​
Rotate AES keys

AES key rotation requires Agent Server version 0.17.0.dev3 or later, the PostgreSQL checkpointer with PREFER_GRPC_CHECKPOINTER=true, and the Go store with LANGGRAPH_STORE_BACKEND=grpc. Python, custom, SQLite, and MongoDB checkpointers do not support rotation.
Agent Server encrypts new data with LANGGRAPH_AES_KEY. Key envelopes identify which configured key decrypts each value. When Agent Server reads data encrypted with an old key, it returns the plaintext and lazily re-encrypts the stored value with the current key. To rotate a key:
  1. Configure the current primary key and future key on every replica:
  2. Roll out this configuration to every replica.
  3. After every replica can decrypt both keys, switch LANGGRAPH_AES_KEY to the future key.
  4. Retain the old key in both compatibility settings:
    LANGGRAPH_AES_LEGACY_KEY decrypts untagged historical ciphertext. LANGGRAPH_AES_FALLBACK_KEYS decrypts tagged ciphertext created with an old key.
  5. Keep old keys configured until telemetry confirms they are no longer needed.
  • Never change the primary key before every replica can decrypt both keys.
  • Lazy rotation updates only accessed rows. Cold rows and compare-and-swap misses may retain old ciphertext.
  • Removing keys early can make retained data unreadable.
  • Once key-envelope ciphertext exists, Agent Server versions without envelope support cannot read it.
Connect these docs to your agent of choice via MCP for real-time answers.
Edit this page on GitHub or file an issue.