SDK Guide

The @zexio/zms-sdk allows you to interact with the ZMS Vault programmatically within your Node.js or TypeScript applications.

Installation

npm install @zexio/zms-sdk
# or
pnpm add @zexio/zms-sdk

Token-Only Authentication

ZMS follows a modern M2M (Machine-to-Machine) authentication pattern. You only need a ZMS_TOKEN to initialize the client. The client will automatically resolve the organization and project scope based on the token.

Initializing the Client

import { ZmsClient } from '@zexio/zms-sdk';
 
const zms = new ZmsClient({
  baseUrl: 'http://localhost:3030',
  token: process.env.ZMS_TOKEN // Required
});

Fetching Secrets

Fetch All Secrets for Service

Retrieves all secrets for the project and service scoped to the token.

const secrets = await zms.getSecrets();
// Returns { "DATABASE_URL": "...", "API_KEY": "..." }

Fetch a Specific Secret

Retrieves a single secret by its key name.

const databaseUrl = await zms.getSecret('DATABASE_URL');
// Returns "postgres://..."

Best Practices

⚡ Use zms run Instead of SDK (When Possible)

For most applications, we recommend using the zms run command to inject secrets into process.env at startup. This eliminates the need for SDK boilerplate in your business logic.

🔒 Never Log Secret Values

Ensure that you treat values returned by the SDK as sensitive. Never output them to logs or error messages.