Quick Start

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

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:

Secret

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 secret = await workos.vault.createSecret({
  name: 'foo-corp-secret',
  value: 'secret value',
  context: { organizationId: organization.id },
});

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

const updatedSecret = await workos.vault.updateSecret({
  id: secret.id,
  value: 'new value',
  versionCheck: secret.metadata.versionId,
});

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

const id = 'secret_51B0AC67C2FB4247AC5ABDDD3C701BDC';

// List all secrets
const secrets = await workos.vault.listSecrets();

// Fetch metadata for a secret
const metadata = await workos.vault.describeSecret({ id });

// Fetch full secret
const secret = await workos.vault.readSecret({ id });

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

await workos.vault.deleteSecret({ id: secret.id });