Overview
With E2EE enabled:- Your client fetches the model public key from attestation.
- Your client encrypts
messages[].contentlocally. - Gateway processes encrypted input and returns encrypted output.
- Your client decrypts response content locally.
Supported Endpoints
POST /v1/chat/completions
Required Headers
Always include:X-Signing-Algo:ecdsaored25519X-Client-Pub-Key: client public key (hex)X-Model-Pub-Key: model public key from attestation (hex)
X-E2EE-Version: 2X-E2EE-Nonce: <unique, at least 16 chars>X-E2EE-Timestamp: <unix seconds>
Step 1: Fetch Model Public Key (Attestation)
signing_public_key from the response and use it as X-Model-Pub-Key.
Step 2: Generate Client Key Pair
Generate an ephemeral client key pair (matchingX-Signing-Algo) for better forward secrecy.
Step 3: Encrypt Message Content
For encrypted fields (e.g.messages[i].content), use:
ephemeral_public_key || nonce(12 bytes) || ciphertext
Then hex-encode the result and place it into JSON.
v1 vs v2 (What’s Different)
| Item | v1 | v2 |
|---|---|---|
| Security mode | Legacy compatibility mode | Strict mode (recommended) |
| Extra headers | No nonce/timestamp required | Requires nonce + timestamp |
| AAD binding | Not used | Used for request/response context binding |
| Replay protection | Not enforced by protocol headers | Enforced with nonce/timestamp validation |
| Recommendation | For legacy clients only | Default for all new integrations |
Step 4A: Send E2EE Request (v1 Example)
X-E2EE-Applied: trueX-E2EE-Version: 1X-E2EE-Algo: ecdsa|ed25519
Step 4B: Send E2EE Request (v2 Example)
X-E2EE-Applied: trueX-E2EE-Version: 2X-E2EE-Algo: ecdsa|ed25519
Step 5: Decrypt Response
Decrypt:choices[*].message.contentchoices[*].message.reasoning_content(if present)
End-to-End Python Example
Python example (ECDSA, non-streaming, v2)
Python example (ECDSA, non-streaming, v2)
Common Errors
e2ee_header_missinge2ee_invalid_signing_algoe2ee_invalid_public_keye2ee_model_key_mismatche2ee_invalid_versione2ee_invalid_noncee2ee_invalid_timestampe2ee_replay_detectede2ee_decryption_failed
Best Practices
- Use v2 for all new integrations.
- Use a unique nonce for every request.
- Avoid logging plaintext prompts/responses.
- Prefer ephemeral client keys.