Quick Start

To get the most out of these guides, you’ll need:

• A WorkOS account

Sign in to your WorkOS Dashboard account and create a new Organization.

In this guide, we will walk you through what you will need to set up Vault for securing and isolating organization-specific data:

• Encrypt and store data linked to an organization
• Retrieve the encrypted data
• Delete an object that’s no longer in use

Object

Represents an encrypted key-value item stored by Vault.

Organization

Describes an organization whose users sign in with a SSO Connection, or whose users are synced with a Directory Sync Connection.

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.

To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as WORKOS_API_KEY and WORKOS_CLIENT_ID, and pass them to the SDKs either as environment variables or directly in your app’s configuration based on your preferences.

WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

The Vault API and SDKs provide a method to encrypt and store a blob of data linked to a WorkOS organization. The encryption key used will be both unique to the KV item and cryptographically isolated from all other organizations.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const organization = await workos.organizations.getOrganization(
  'org_01EHZNVPK3SFK441A1RGBFSHRT',
);

const object = await workos.vault.createObject({
  name: 'foo-corp-secret',
  value: 'secret value',
  context: { organizationId: organization.id },
});

Once created, the key context for an object cannot be changed. Only the value can be updated. The expected version of the object can be provided as a consistency lock when writing to the object.

const updatedObject = await workos.vault.updateObject({
  id: object.id,
  value: 'new value',
  versionCheck: object.metadata.versionId,
});

Objects can be listed, returning just the names of the objects. The metadata for each object can be queried – this provides more information about it without needing to decrypt the actual value. Fetching the object value will return the same metadata in addition to the unencrypted value.

const id = 'secret_51B0AC67C2FB4247AC5ABDDD3C701BDC';

// List all objects
const objects = await workos.vault.listObjects();

// Fetch metadata for an object
const metadata = await workos.vault.describeObject({ id });

// Fetch full object
const object = await workos.vault.readObject({ id });

When an object is no longer needed it can be marked for deletion. This will make the object unavailable to API operations, but the data will not be immediately deleted.

await workos.vault.deleteObject({ id: object.id });