> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://infonite.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://infonite.dev/_mcp/server.
# Payload Encryption
Everything sensitive the platform hands you — the results of a session, the payload of a webhook — can be delivered **encrypted with a key that is yours**. You mint it, you pass it once when you create the session, and from that moment the records exist in readable form only inside your own process.
Encrypted values are always **self-describing**: the name of the scheme, `::`, and the Base64 of the encrypted bytes. Read the prefix first and handle what it says.
```
aes::U2FsdGVkX19...
^^^ ^^^^^^^^^^^^^^
| └── Base64 of the encrypted bytes
└── the scheme — here, AES-256-GCM
```
**This page is about `aes::`** — AES-256-GCM, the scheme behind every session result and webhook payload, and the one your integration will use. The platform also accepts values encrypted *towards* it with RSA, for credentials travelling the other way; that is a different problem with a different answer, and it lives at the [end of this page](#sending-values-in-the-other-direction).
---
## Encrypting with AES-256-GCM
**AES-256-GCM** (Galois/Counter Mode) with a 12-byte IV and a 16-byte authentication tag. GCM is authenticated encryption: decryption fails loudly if a single byte was altered in transit, so a payload that decrypts is a payload nobody touched.
The encrypted payload is delivered as a string prefixed with `aes::` followed by the Base64-encoded binary data.
Prefix aes:: (Discard first)
\+
Base64 Encoded Envelope U2FsdGVkX19... (Decode to raw binary)
IV / Nonce First 12 bytes
Ciphertext Middle bytes
Auth Tag Last 16 bytes
The raw byte layout after decoding the Base64 portion follows a strict concatenation sequence:
| Component | Size | Description |
| :--------------------- | :------------- | :----------------------------------------------------- |
| **IV (Nonce)** | 12 bytes | Cryptographically secure random initialization vector. |
| **Ciphertext** | Variable bytes | The actual encrypted JSON string. |
| **Authentication Tag** | 16 bytes | GMAC integrity and authenticity validation tag. |
---
## Encryption & Decryption Workflows
Here is the technical walkthrough for implementing the cryptography pipelines.
### Encryption Walkthrough
#### Encryption Walkthrough
**Generate IV**: Create a cryptographically secure random 12-byte initialization vector (nonce).
**Encrypt**: Encrypt the plaintext payload using the AES-256-GCM algorithm with your allocated 32-byte key and the generated IV.
**Assemble Envelope**: Concatenate the `IV` (12 bytes), the resulting `ciphertext` (variable bytes), and the 16-byte `authentication tag` returned by the cipher.
**Encode and Prefix**: Base64-encode the concatenated byte block and prepended with the `aes::` prefix.
### Decryption Walkthrough
#### Decryption Walkthrough
**Remove Prefix**: Strip the `aes::` prefix from the string.
**Decode Base64**: Decode the remaining Base64-encoded string to extract the raw bytes.
**Extract Payload Parts**:
* **IV (Initialization Vector)**: Extract the first 12 bytes.
* **Tag (Authentication Tag)**: Extract the last 16 bytes.
* **Ciphertext**: Extract the middle bytes (everything between the first 12 bytes and the last 16 bytes).
**Decrypt**: Decrypt the Ciphertext using the AES-256-GCM algorithm with your allocated Session `aes_key` (configured during [Create Session](api:POST/es-public-administration/v1/manager/init)), the extracted IV, and the Tag.
---
## Interactive Cryptography Sandbox
Test your GCM encryption and decryption logic directly in this sandbox tool. Toggle the switcher below to change between the Encrypt and Decrypt pipelines.
AES-256-GCM Playground
Encrypt Mode Decrypt Mode
AES Key (32-byte Base64)
Generate Key
Plaintext JSON to Encrypt
Encrypted Payload (prefixed with aes::)
Encrypt Plaintext Decrypt Payload
Output Results
Output will appear here...
---
## Implementation Code Examples
Select your preferred programming language tab below to copy production-ready code examples matching this AES-256-GCM specification.
```javascript title="Node.js"
const crypto = require('node:crypto');
/**
* Encrypt plaintext using AES-256-GCM and return the base64-encoded string prefixed with "aes::".
* @param {Buffer} key - 32-byte AES key
* @param {Buffer} plaintext - Data to encrypt
* @returns {string} Encrypted payload prefixed with "aes::"
*/
function encryptGcm(key, plaintext) {
if (key.length !== 32) throw new Error('Key must be exactly 32 bytes');
const iv = crypto.randomBytes(12);
const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
const tag = cipher.getAuthTag();
const envelope = Buffer.concat([iv, ciphertext, tag]);
return `aes::${envelope.toString('base64')}`;
}
/**
* Decrypt an aes:: prefixed Base64 string using AES-256-GCM.
* @param {Buffer} key - 32-byte AES key
* @param {string} payloadB64 - Encrypted payload prefixed with "aes::"
* @returns {Buffer} Decrypted plaintext bytes
*/
function decryptGcm(key, payloadB64) {
if (key.length !== 32) throw new Error('Key must be exactly 32 bytes');
const blob = Buffer.from(payloadB64.replace(/^aes::/, ''), 'base64');
const iv = blob.subarray(0, 12);
const tag = blob.subarray(blob.length - 16);
const ciphertext = blob.subarray(12, blob.length - 16);
const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
decipher.setAuthTag(tag);
return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
}
// Example usage:
const key = Buffer.from('9127m7kfzkNxS14A2U71lEzcyaqv9K5xDLtKuFTg+84=', 'base64');
// Encrypt example
const secretData = Buffer.from(JSON.stringify({ test: 'You got it!!!' }), 'utf8');
const encrypted = encryptGcm(key, secretData);
console.log('Encrypted Payload:', encrypted);
// Decrypt example
const decrypted = decryptGcm(key, encrypted);
console.log('Decrypted Plaintext:', decrypted.toString('utf8'));
```
```python title="Python"
import os
import base64
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
def encrypt_gcm(key: bytes, plaintext: bytes) -> str:
"""
Encrypts plaintext using AES-256-GCM and returns a base64 string prefixed with "aes::".
"""
iv = os.urandom(12)
cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend=default_backend())
encryptor = cipher.encryptor()
ciphertext = encryptor.update(plaintext) + encryptor.finalize()
# Concatenate IV || Ciphertext || Tag
blob = iv + ciphertext + encryptor.tag
envelope = base64.b64encode(blob).decode("utf-8")
return f"aes::{envelope}"
def decrypt_gcm(key: bytes, payload_b64: str) -> bytes:
"""
Decrypts an aes:: prefixed Base64 GCM payload using a 32-byte key.
"""
# Strip prefix and decode Base64
clean_payload = payload_b64.replace("aes::", "")
blob = base64.b64decode(clean_payload)
# Extract components (IV, ciphertext, tag)
iv, encrypted_data, tag = blob[:12], blob[12:-16], blob[-16:]
# Execute GCM Decryption
cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag), backend=default_backend())
decryptor = cipher.decryptor()
return decryptor.update(encrypted_data) + decryptor.finalize()
# Example usage:
key_bytes = base64.b64decode("9127m7kfzkNxS14A2U71lEzcyaqv9K5xDLtKuFTg+84=")
# Encrypt example
plaintext_bytes = b'{"test": "You got it!!!"}'
encrypted_payload = encrypt_gcm(key_bytes, plaintext_bytes)
print("Encrypted Payload:", encrypted_payload)
# Decrypt example
decrypted = decrypt_gcm(key_bytes, encrypted_payload)
print("Decrypted Plaintext:", decrypted.decode("utf-8"))
```
```java title="Java"
import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.ByteBuffer;
import java.security.SecureRandom;
import java.util.Base64;
public class AesGcmCoder {
private static final SecureRandom random = new SecureRandom();
public static byte[] fromBase64(String b64) {
if (b64.startsWith("aes::")) b64 = b64.substring(5);
return Base64.getDecoder().decode(b64);
}
public static byte[] concat(byte[]... parts) {
int total = 0;
for (byte[] p : parts) total += p.length;
ByteBuffer buf = ByteBuffer.allocate(total);
for (byte[] p : parts) buf.put(p);
return buf.array();
}
/**
* Encrypts plaintext using AES-256-GCM. Returns envelope prefixed with "aes::".
*/
public static String encryptGcm(byte[] key, byte[] plaintext) throws Exception {
if (key.length != 32) throw new IllegalArgumentException("Key must be 32 bytes");
byte[] iv = new byte[12];
random.nextBytes(iv);
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
GCMParameterSpec gcmSpec = new GCMParameterSpec(128, iv);
SecretKeySpec keySpec = new SecretKeySpec(key, "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec, gcmSpec);
byte[] cipherTextWithTag = cipher.doFinal(plaintext);
byte[] ciphertext = new byte[cipherTextWithTag.length - 16];
byte[] tag = new byte[16];
System.arraycopy(cipherTextWithTag, 0, ciphertext, 0, ciphertext.length);
System.arraycopy(cipherTextWithTag, ciphertext.length, tag, 0, 16);
byte[] blob = concat(iv, ciphertext, tag);
return "aes::" + Base64.getEncoder().encodeToString(blob);
}
/**
* Decrypts GCM payload byte structure: IV(12) || CIPHERTEXT || TAG(16)
*/
public static byte[] decryptGcm(byte[] key, String payloadB64) throws Exception {
if (key.length != 32) throw new IllegalArgumentException("Key must be 32 bytes");
byte[] blob = fromBase64(payloadB64);
byte[] iv = new byte[12];
byte[] tag = new byte[16];
byte[] ciphertext = new byte[blob.length - 12 - 16];
System.arraycopy(blob, 0, iv, 0, 12);
System.arraycopy(blob, 12, ciphertext, 0, ciphertext.length);
System.arraycopy(blob, blob.length - 16, tag, 0, 16);
// Java JCE GCM decryptor expects Ciphertext concatenated with Tag
byte[] ctWithTag = concat(ciphertext, tag);
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
GCMParameterSpec gcmSpec = new GCMParameterSpec(128, iv);
SecretKeySpec keySpec = new SecretKeySpec(key, "AES");
cipher.init(Cipher.DECRYPT_MODE, keySpec, gcmSpec);
return cipher.doFinal(ctWithTag);
}
public static void main(String[] args) throws Exception {
byte[] keyBytes = Base64.getDecoder().decode("9127m7kfzkNxS14A2U71lEzcyaqv9K5xDLtKuFTg+84=");
byte[] plaintext = "{\"test\": \"You got it!!!\"}".getBytes("UTF-8");
// Encrypt
String encrypted = encryptGcm(keyBytes, plaintext);
System.out.println("Encrypted Payload: " + encrypted);
// Decrypt
byte[] decrypted = decryptGcm(keyBytes, encrypted);
System.out.println("Decrypted Plaintext: " + new String(decrypted, "UTF-8"));
}
}
```
---
## Sending values in the other direction
Everything above solves one problem: **we send you data, and only you can read it.** There is a second, separate problem — **you send us a secret, and only we can read it** — and it needs a different kind of key.
It comes up when your server hands us something an engine will use on the end user's behalf, typically a set of credentials. A shared key is the wrong tool there: whoever can encrypt could also decrypt, and both sides holding the same secret is exactly what you do not want for someone else's password.
So each application gets an **RSA key pair whose private half is generated inside the platform and never leaves it**. You receive the **public key** — a PEM you paste into your key store, exactly as you would any other public key. Encrypt with it and nobody downstream can read the value: not an intermediary, not a log, and not your own process once the value has been sent. *(An X.509 certificate carrying that same public key is available too, for stacks that expect one; it is self-signed, so it is a container with a validity window rather than a chain of trust — the key inside it is what does the work.)*
Two schemes travel that way, and the choice between them is a size limit, not a preference:
| Prefix | Scheme | Use it for |
| :--------- | :----------------------------------- | :---------------------------------------------------------------------------------- |
| `rsa::` | RSA, PKCS#1 v1.5 | A single short value. A 2048-bit key caps the payload at roughly 245 bytes. |
| `hybrid::` | AES-256-GCM under an RSA-wrapped key | **Everything else** — a whole credentials object exceeds the RSA limit immediately. |
#### [Direct Executions — coming](mailto:support@infonite.tech)
The full walkthrough — obtaining your public key, choosing between `rsa::` and `hybrid::`, encrypting a whole parameter set versus individual values, and what a certificate renewal does and does not change — ships with the Direct Executions API reference. Until then, support will set you up.