Payload Encryption

What a flow session pushes to your servers — the payload of every webhook it sends, its results included — 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 those payloads exist in readable form only inside your own process. What you read with your application secret — the results endpoint, the attachments — answers over TLS and is not encrypted with it: Financial Rider and Spain Public Administration say exactly what the key covers.

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.

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. They are the same five moves read in opposite directions — the one you implement is the top row:

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.

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'));

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:

The two envelopes, byte by byte

rsa:: is the simple one: the value’s UTF-8 bytes, encrypted with the public key using RSA PKCS#1 v1.5 padding, Base64-encoded, prefixed. Nothing else travels.

hybrid:: carries two things in one Base64 string: a fresh AES-256 key that only the platform can unwrap, and the value encrypted with that key — the same AES-256-GCM envelope this page describes above, laid out the same way.

Encrypting towards us — code examples

Each example reads the public key exactly as the Console gives it — the PEM you copy or download from App Settings → Security & Keys — and produces both envelopes. All three were run against the platform’s own decryption before being published here.

const crypto = require('node:crypto');
const fs = require('node:fs');
/** The PEM from the Console, as downloaded. */
function loadPublicKey(pem) {
  return crypto.createPublicKey(pem);
}
/** One short value (up to 245 bytes with a 2048-bit key): RSA PKCS#1 v1.5, prefixed "rsa::". */
function encryptRsa(publicKey, value) {
  const ciphertext = crypto.publicEncrypt(
    { key: publicKey, padding: crypto.constants.RSA_PKCS1_PADDING },
    Buffer.from(value, 'utf8')
  );
  return `rsa::${ciphertext.toString('base64')}`;
}
/** Anything, any size: a fresh AES-256 key wrapped with RSA, then AES-256-GCM. Prefixed "hybrid::". */
function encryptHybrid(publicKey, value) {
  const plaintext = Buffer.from(typeof value === 'string' ? value : JSON.stringify(value), 'utf8');
  const aesKey = crypto.randomBytes(32);
  const iv = crypto.randomBytes(12);
  const cipher = crypto.createCipheriv('aes-256-gcm', aesKey, iv);
  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
  const wrappedKey = crypto.publicEncrypt(
    { key: publicKey, padding: crypto.constants.RSA_PKCS1_PADDING },
    aesKey
  );
  // wrapped key (256 bytes for a 2048-bit key) || IV (12) || ciphertext || tag (16)
  const blob = Buffer.concat([wrappedKey, iv, ciphertext, cipher.getAuthTag()]);
  return `hybrid::${blob.toString('base64')}`;
}
// Example usage:
const publicKey = loadPublicKey(fs.readFileSync('public.pem', 'utf8'));
console.log(encryptRsa(publicKey, 's3cret-p4ssw0rd'));
console.log(encryptHybrid(publicKey, { username: '44444444A', password: 's3cret-p4ssw0rd' }));