SDK — Secrets

Get a Secret

const value = await pb.secrets.get('DATABASE_URL', {
  vault: 'my-app',       // optional if default set
  env: 'production',      // optional
});
// Returns: "postgres://user:pass@host/db"

Returns the decrypted plaintext value as a string.

Options

interface GetSecretOptions {
  vault?: string;  // vault name or ID
  env?: string;    // environment name
}

Set a Secret

await pb.secrets.set('DATABASE_URL', 'postgres://...', {
  vault: 'my-app',
  env: 'production',
  description: 'Main database connection',
});

Creates the secret if it doesn’t exist, or updates it (creating a new version) if it does. The value is encrypted client-side before transmission.

Options

interface SetSecretOptions {
  vault?: string;
  env?: string;
  description?: string;
  tags?: string[];
}

Delete a Secret

await pb.secrets.delete('OLD_KEY', {
  vault: 'my-app',
  env: 'production',
});

List Secrets

const secrets = await pb.secrets.list({
  vault: 'my-app',
  env: 'production',
});

Returns an array of SecretData:

interface SecretData {
  id: string;
  name: string;
  tags: string[];
  version: number;
  created_at: string;
  updated_at: string;
  encrypted_value: string;
  environment_id: string;
}

Note

list() returns metadata and encrypted values. Use get() to retrieve decrypted plaintext values.

Get All Secrets (Key-Value)

const secrets = await pb.secrets.getAll({
  vault: 'my-app',
  env: 'production',
});
// Returns: { DATABASE_URL: "postgres://...", API_KEY: "sk-..." }

Returns a Record<string, string> of all decrypted secrets — useful for injecting into environment variables.

Version History

const versions = await pb.secrets.versions('DATABASE_URL', {
  vault: 'my-app',
  env: 'production',
});

Returns an array of SecretVersionData:

interface SecretVersionData {
  id: string;
  secret_id: string;
  version: number;
  encrypted_value: string;
  created_by: string;
  created_at: string;
}

Complete Example

import { PassBox } from '@pabox/sdk';

const pb = new PassBox({ token: process.env.PASSBOX_TOKEN });

// Set up defaults
pb.setDefaultVault('my-app');

// Store secrets
await pb.secrets.set('DB_HOST', 'localhost', { env: 'development' });
await pb.secrets.set('DB_HOST', 'db.prod.internal', { env: 'production' });

// Retrieve
const devHost = await pb.secrets.get('DB_HOST', { env: 'development' });
const prodHost = await pb.secrets.get('DB_HOST', { env: 'production' });

// Get all for injection
const prodSecrets = await pb.secrets.getAll({ env: 'production' });
Object.assign(process.env, prodSecrets);