Outbound Relay is an invisible decryption proxy that lets you share encrypted data with third-party APIs, without the third-party having to decrypt any fields themselves.

Outbound Relay is available in all our server-side SDKs (Node.js, Python, Ruby and Java) and can be configured within the Evervault Dashboard.

Under the hood, Outbound Relay is an HTTP CONNECT proxy that intercepts requests from your API to specific third-party hostnames, terminates TLS and swaps encrypted data with the original plaintext.

By the time the request reaches the third-party API, all fields are decrypted, and the request will appear as a valid API request for the third-party.

Getting started

To begin using Outbound Relay, you will need an API written in one of the languages we have a server-side SDK available for. This API will only handle Evervault-encrypted data, but will interact with third-party APIs as if Evervault Encryption is invisible.

Include the Evervault SDK

To use Outbound Relay, simply include and initialize the Evervault SDK in your application and enable outbound relay. Outbound Relay can be used in any of our server-side SDKs.

1
const Evervault = require('@evervault/sdk');
2
3
const evervault = new Evervault('<API_KEY>');
4
evervault.enableOutboundRelay();

Create an API to receive data

In this example, we will use RequestBin to generate an ephemeral API that will log all requests, including their payloads. We can create a RequestBin by navigating to requestbin.com/r, where we will be given a temporary URL which we can send requests to.

Using HTTPS libraries in the language of your choice, we can send a request to the RequestBin, and the Evervault SDK will automatically intercept requests and route them through Outbound Relay.

1
const Evervault = require('@evervault/sdk');
2
const axios = require('axios');
3
4
const evervault = new Evervault('<API_KEY>', {
5
	enableOutboundRelay: true
6
});
7
8
const REQUESTBIN_URL = '[YOUR_REQUESTBIN_URL]';
9
10
(async () => {
11
	const ssn = await evervault.encrypt('123-4567-123');
12
	const result = await axios.post(REQUESTBIN_URL, {
13
		name: 'Claude Shannon',
14
		ssn
15
	});
16
17
	console.log(result);
18
})();

You should now see the request appear in the RequestBin logs with the data still encrypted. We can now configure Outbound Relay to decrypt all sensitive data being sent to the RequestBin.

Configure endpoints to decrypt

Once you have included the Evervault SDK in your application, Outbound Relay can be enabled for specific domains within the Evervault Dashboard.

Within the Outbound Relay tab in your App, you can specify the hostnames of the APIs you want to send encrypted data to. In this case, we’ll add our RequestBin as an Outbound Relay Destination.

If we run our application and send the request again, we’ll be able to see another request in our RequestBin. This time, the encrypted ssn that we sent from our application was automatically decrypted by Outbound Relay before being passed to the RequestBin.

This flow means you can still interact with any third-party API that requires sensitive data in plaintext, while keeping it encrypted at all times within your application.

What’s next?

Congratulations! You have successfully configured Outbound Relay to share encrypted data with a third-party API without handling it in plaintext.

If you need to process encrypted data using your own code, check out Functions.

Response Encryption

If you would like to encrypt responses from the third-party API before they reach your server (for example, encrypting bank details returned from a payments API), you can specify fields or files to encrypt in the Settings of your Outbound Relay Destination.

File Decryption

Outbound Relay supports decrypting files and text fields in multipart/form-data uploads.

For Response Encryption, Outbound Relay supports encrypting files and text-fields in multipart/form-data uploads. Simply add the names of the relevant fields in your form to your fields to encrypt.

There is currently a per-request limit of 25 MB for encryption/decryption.