Guides

Encrypt access tokens with Outbound Relay

Many services collect and manage access tokens for third-party APIs. Access tokens include secrets like OAuth Access Tokens, API keys and raw credentials that developers collect from their end-users to authenticate with third-party APIs.

Access tokens are generally extremely sensitive pieces of data. If they are compromised, they potentially grant an attacker complete access to a customer’s account on the service. This could be anything from access to online banking, sensitive cloud infrastructure or email inboxes. In this section, you will encrypt an access token using outbound relay.

Using Outbound Relay, you can interact with any third-party REST API without ever handling your customers’ sensitive access tokens in plaintext. Outbound Relay is fully compatible with standards like OAuth 2.


Getting Started

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. With Outbound Relay, you can use Evervault-encrypted access tokens to access any third-party service, without implementing any decryption logic yourself.

The Evervault docs site exposes two API endpoints to emulate what a typical authentication flow might look like.

POST /api/fetchToken

Accepts a password and returns an ephemeral JWT access token

shamir:~$
curl -X POST https://docs.evervault.com/api/fetchToken \
-H 'Content-Type: application/json' \
--data '{"name": "Claude", "password": "opensesame"}'

If your request was successfully authenticated using the password provided, the API will return the following response with an access token:

POST/api/fetchToken
200Ok
{
"authenticated": true,
"message": "Hello, Claude! You have been successfully authenticated. Your access token is attached.",
"accessToken": "eyJ..."
}

If the authentication failed, the API will return the following response:

POST/api/fetchToken
401Unauthorized
{
"authenticated": false,
"message": "Hello, Claude! Unfortunately, your authentication attempt was unsuccessful. Please try and request an access token again."
}

POST /api/authenticatedEndpoint

Accepts an Authorization header with a JWT access token and returns a 200 OK status code if authentication was successful, or a 401 Unauthorized status code if authentication failed.

shamir:~$
curl -X POST https://docs.evervault.com/api/authenticatedEndpoint \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [ACCESS_TOKEN]'

If your request was successfully authenticated, the API will return the following response:

POST/api/authenticatedEndpoint
200Ok
{
"authenticated": true,
"message": "Hello, Claude! You have been successfully authenticated."
}

If the authentication failed, the API will return the following response:

POST/api/authenticatedEndpoint
401Unauthorized
{
"authenticated": false,
"message": "Hello, Claude! Unfortunately your authentication attempt was unsuccessful."
}

The code below contains a sample application which will authenticate with the API and fetch an access token which can later be stored.

1
const Evervault = require("@evervault/sdk");
2
const evervault = new Evervault("<API_KEY>", {
3
enableOutboundRelay: true,
4
});
5
6
const axios = require("axios");
7
8
// The password below can be stored in a database, fully encrypted using Evervault
9
const password = "ev:encrypted_string";
10
11
(async () => {
12
const { data: accessToken } = await axios.post(
13
"https://docs.evervault.com/api/fetchToken",
14
{
15
name: "Claude",
16
password,
17
}
18
);
19
20
console.log("Access token: ", accessToken);
21
22
const { data: authenticatedResponse } = await axios.post(
23
"https://docs.evervault.com/api/authenticatedEndpoint",
24
{
25
name: "Claude",
26
},
27
{
28
headers: {
29
authorization: `Bearer ${accessToken}`,
30
},
31
}
32
);
33
34
console.log("Response from authenticated API: ", authenticatedResponse);
35
})();

By default, Outbound Relay will automatically decrypt the password being passed to the API, so it is received in plaintext.

Encrypt the access token in the response using Outbound Relay

To encrypt the access token in the JSON response, go to the Outbound Relay section in the Evervault Dashboard and add a new Outbound Relay Destination, specifying docs.evervault.com as the domain name.

Once you have added the Outbound Relay Destination, navigate to the Response Encryption section and add $.accessToken as a field to encrypt. Fields to encrypt can be defined using JSONPath Selectors.

If you run the application again, the code should continue to run as normal, and authentication will be successful. If you check the application logs, you will see that the access token is logged as an Evervault-encrypted string. This means your infrastructure is never handling the access token in plaintext, and it can be stored in your database fully-encrypted.

When you send the request to /api/authenticatedEndpoint, Outbound Relay will automatically decrypt the Evervault-encrypted access token within the Authorization header. No additional code changes are required to use the third-party API with encrypted access tokens.

Congratulations! You have successfully encrypted access tokens using Outbound Relay.