toc

Node.js SDK

A full reference of our Node.js SDK.

You can use our Node.js SDK to:

  1. Encrypt data at your server
  2. Run your Cages
  3. Encrypt/decrypt data with Relay

You can use our Node.js SDK to encrypt data — rather than with Relay — and still send it to a third-party via Relay. Encrypting with our backend SDKs is best for developers who want to avoid the network latency of Relay and/or want to avoid sending plaintext data to Relay to be encrypted.

Encrypting data with our backend SDKs instead of Relay may expose you to greater compliance burden because plaintext data touches your server before it is encrypted.

You don’t need to change your database configuration. You can store Evervault-encrypted data in your database as you would the plaintext version.

Installation

Our Node.js SDK is distributed via npm, and can be installed using your preferred package manager.

bash
# Install using npm
npm install @evervault/sdk
# Install using Yarn
yarn add @evervault/sdk

Initialization

The Evervault Node.js SDK will automatically route all outbound HTTPS requests through Relay for decryption by overriding your default HTTP Agent. To disable this behaviour, set the intercept value to false in the initialization options.

javascript
const Evervault = require('@evervault/sdk');
// Initialize the client with your team’s API key
const evervault = new Evervault('<YOUR_API_KEY>');
// Encrypt your data
const encrypted = await evervault.encrypt({ name: 'Alice' });
// Process the encrypted data in a Cage
const result = await evervault.run('hello-cage', encrypted);

Reference

The Evervault Node.js SDK exposes three functions:

  • @evervault/sdk() (constructor)
  • evervault.encrypt()
  • evervault.run()

@evervault/sdk()

The SDK constructor accepts two parameters:

  1. Your team's API key
  2. Optional configuration parameters
javascript
const Evervault = require('@evervault/sdk');
const evervault = new Evervault(apiKey: String, config: Object);
ParameterTypeDescription
apiKeyStringYour team's API key
configObjectOptions for the SDK session
OptionTypeDefaultDescription
interceptBooleantrueRoute outbound requests through Evervault to automatically decrypt encrypted fields.
ignoreDomainsArray[]Requests sent to any of the domains in this list will not be intercepted

evervault.encrypt()

evervault.encrypt() encrypts data for use in your Cages and through Relay. To encrypt data at the server, simply pass an object or string into the evervault.encrypt() function. Store the encrypted data in your database as normal.

javascript
async evervault.encrypt(data: Object | String);
ParameterTypeDescription
dataObject or StringData to be encrypted.

evervault.run()

evervault.run() lets you invoke a Cage with a given payload.

javascript
async evervault.run(cageName: String, data: Object[, options: Object]);
ParameterTypeDescription
cageNameStringName of the Cage to be run.
dataObjectPayload for the Cage.
optionsObjectOptions for the Cage run.
OptionTypeDefaultDescription
asyncBooleanfalseRun your Cage in async mode. Async Cage runs will be queued for processing.
versionNumberundefinedSpecify the version of your Cage to run. By default, the latest version will be run.

Was this page useful?