Installation

npm install @ghoststack/vault-sdk

Requires Node.js 18 or later. The SDK is written in TypeScript and ships with type declarations.

Vault.connect()

Creates a new Vault client instance.

import { Vault } from "@ghoststack/vault-sdk";

const vault = await Vault.connect({
  tenant: string;     // Organization slug
  token: string;      // API token
  baseUrl?: string;   // Optional; defaults to https://vault.ghoststack.dev
  timeout?: number;   // Request timeout in ms; defaults to 30000
});

The returned vault object provides access to all subsystems: credentials, leases, team, tokens, and auditLog.

vault.credentials

credentials.create(params)

Creates a new credential.

const credential = await vault.credentials.create({
  name: string;                     // Unique name within the tenant
  type: CredentialType;             // "api-key" | "oauth-token" | "ssh-key" | "tls-certificate" | "database-url" | "generic-secret"
  value: string;                    // The secret value
  metadata?: Record<string, string>; // Optional key-value pairs
  policy?: CredentialPolicy;        // Optional lease policy
});

Returns: Credential (without the value field).

credentials.get(params)

Retrieves a credential’s metadata. Does not return the value. To get the value, create a lease.

const credential = await vault.credentials.get({
  name: string;
});

Returns: Credential.

credentials.list(params?)

Lists credentials in the tenant.

const credentials = await vault.credentials.list({
  type?: CredentialType;             // Filter by type
  state?: "active" | "rotated" | "revoked"; // Filter by state
  filter?: Record<string, string>;  // Filter by metadata fields
  limit?: number;                   // Page size; default 50
  offset?: number;                  // Pagination offset
});

Returns: Credential[].

credentials.update(params)

Updates a credential’s metadata or policy. Does not change the value (use rotate for that).

await vault.credentials.update({
  name: string;
  metadata?: Record<string, string>;
  policy?: CredentialPolicy;
});

Returns: Credential.

credentials.rotate(params)

Replaces a credential’s value. The old value transitions to the rotated state. Active leases continue using the old value until they expire.

await vault.credentials.rotate({
  name: string;
  newValue: string;
  metadata?: Record<string, string>; // Optional; merged with existing metadata
});

Returns: Credential.

credentials.revoke(params)

Permanently revokes a credential. All active leases are immediately invalidated.

await vault.credentials.revoke({
  name: string;
});

Returns: void.

vault.leases

leases.create(params)

Creates a new lease for a credential.

const lease = await vault.leases.create({
  credentialName: string;  // Name of the credential to lease
  ttl: string;             // Duration string: "5m", "1h", "8h"
  identity?: Identity;     // Optional; auto-populated from token if omitted
});

Returns: Lease (includes the decrypted value).

leases.get(params)

Retrieves a lease by ID. Does not include the credential value.

const lease = await vault.leases.get({
  leaseId: string;
});

Returns: Lease (without value).

leases.renew(params)

Extends an active lease’s TTL.

await vault.leases.renew({
  leaseId: string;
  ttl: string;       // New TTL from the current time
});

Returns: Lease.

leases.revoke(params)

Revokes an active lease immediately.

await vault.leases.revoke({
  leaseId: string;
});

Returns: void.

leases.list(params?)

Lists leases for a credential or identity.

const leases = await vault.leases.list({
  credentialName?: string;
  state?: "active" | "expired" | "revoked";
  limit?: number;
  offset?: number;
});

Returns: Lease[].

vault.team

team.invite(params)

Invites a user to the tenant.

await vault.team.invite({
  email: string;
  role: "viewer" | "user" | "manager" | "admin";
});

team.getPermissions(params)

Returns effective permissions for a user.

const permissions = await vault.team.getPermissions({
  email: string;
});

team.updateRole(params)

Changes a user’s role.

await vault.team.updateRole({
  email: string;
  role: "viewer" | "user" | "manager" | "admin";
});

team.remove(params)

Removes a user from the tenant.

await vault.team.remove({
  email: string;
});

vault.tokens

tokens.create(params)

Creates a new API token.

const token = await vault.tokens.create({
  name: string;
  role: "viewer" | "user" | "manager" | "admin";
  scope?: {
    credentials: string[];  // Credential name patterns
  };
  expiresAt?: string;       // ISO 8601 timestamp
});

Returns: { token: string; id: string; name: string; expiresAt: string }. The token field is the secret value and is only returned once.

tokens.list()

Lists API tokens (does not include token values).

tokens.revoke(params)

Revokes an API token.

await vault.tokens.revoke({ tokenId: string });

vault.auditLog

auditLog.query(params?)

Queries the audit log.

const entries = await vault.auditLog.query({
  event?: string;              // Event type filter
  credentialName?: string;
  filter?: Record<string, string>; // Filter by identity or metadata fields
  since?: string;              // ISO 8601 timestamp
  until?: string;              // ISO 8601 timestamp
  limit?: number;
  offset?: number;
});

Returns: AuditEntry[].

See Audit Log for event types and entry structure.

Error types

import {
  VaultError, // Base error class
  AuthenticationError, // Invalid or expired token
  AuthorizationError, // Insufficient permissions
  CredentialNotFoundError, // Credential name does not exist
  LeaseExpiredError, // Lease has expired or been revoked
  LeaseLimitError, // maxLeases exceeded
  ValidationError, // Invalid credential value or parameters
} from '@ghoststack/vault-sdk';

All errors extend VaultError and include a code string and message.