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

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.

The raw byte layout after decoding the Base64 portion follows a strict concatenation sequence:

Encryption & Decryption Workflows

Here is the technical walkthrough for implementing the cryptography pipelines.

Encryption Walkthrough

Decryption Walkthrough

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.

Implementation Code Examples

Select your preferred programming language tab below to copy production-ready code examples matching this AES-256-GCM specification.

1
const crypto = require('node:crypto');
2
3
/**
4
 * Encrypt plaintext using AES-256-GCM and return the base64-encoded string prefixed with "aes::".
5
 * @param {Buffer} key - 32-byte AES key
6
 * @param {Buffer} plaintext - Data to encrypt
7
 * @returns {string} Encrypted payload prefixed with "aes::"
8
 */
9
function encryptGcm(key, plaintext) {
10
  if (key.length !== 32) throw new Error('Key must be exactly 32 bytes');
11
  const iv = crypto.randomBytes(12);
12
  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
13
  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
14
  const tag = cipher.getAuthTag();
15
  const envelope = Buffer.concat([iv, ciphertext, tag]);
16
  return `aes::${envelope.toString('base64')}`;
17
}
18
19
/**
20
 * Decrypt an aes:: prefixed Base64 string using AES-256-GCM.
21
 * @param {Buffer} key - 32-byte AES key
22
 * @param {string} payloadB64 - Encrypted payload prefixed with "aes::"
23
 * @returns {Buffer} Decrypted plaintext bytes
24
 */
25
function decryptGcm(key, payloadB64) {
26
  if (key.length !== 32) throw new Error('Key must be exactly 32 bytes');
27
  const blob = Buffer.from(payloadB64.replace(/^aes::/, ''), 'base64');
28
  const iv = blob.subarray(0, 12);
29
  const tag = blob.subarray(blob.length - 16);
30
  const ciphertext = blob.subarray(12, blob.length - 16);
31
  
32
  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
33
  decipher.setAuthTag(tag);
34
  
35
  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
36
}
37
38
// Example usage:
39
const key = Buffer.from('9127m7kfzkNxS14A2U71lEzcyaqv9K5xDLtKuFTg+84=', 'base64');
40
41
// Encrypt example
42
const secretData = Buffer.from(JSON.stringify({ test: 'You got it!!!' }), 'utf8');
43
const encrypted = encryptGcm(key, secretData);
44
console.log('Encrypted Payload:', encrypted);
45
46
// Decrypt example
47
const decrypted = decryptGcm(key, encrypted);
48
console.log('Decrypted Plaintext:', decrypted.toString('utf8'));

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: