Skip to main content
GhostStack
Menu
Navigation

guides

Quick Start: TypeScript SDK

Prerequisites

You need Node.js 18 or later and a Vault account. If you do not have an account yet, sign up at ghoststack.dev and create an organization. Your organization becomes your Vault tenant.

After creating your organization, generate an API token from the dashboard under Settings > API Tokens. You will use this token to authenticate the SDK.

Install the SDK

npm install @ghoststack/vault-sdk

Or with your preferred package manager:

pnpm add @ghoststack/vault-sdk
yarn add @ghoststack/vault-sdk

Connect to Vault

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

const vault = await Vault.connect({
  tenant: 'my-org',
  token: process.env.VAULT_TOKEN,
});

The tenant is your organization’s slug. The token is the API token you generated from the dashboard. Store the token in an environment variable rather than hardcoding it.

Store a credential

const credential = await vault.credentials.create({
  name: 'stripe-secret-key',
  type: 'api-key',
  value: 'sk_live_abc123...',
  metadata: {
    service: 'stripe',
    environment: 'production',
  },
});

console.log(credential.id); // "cred_7f3a..."
console.log(credential.name); // "stripe-secret-key"
console.log(credential.type); // "api-key"

The credential value is encrypted immediately on the server. The response does not include the plaintext value. To retrieve the value, you need to create a lease.

Create a lease

const lease = await vault.leases.create({
  credentialName: 'stripe-secret-key',
  ttl: '30m',
});

console.log(lease.value); // "sk_live_abc123..."
console.log(lease.expiresAt); // 30 minutes from now
console.log(lease.id); // "lease_9b2c..."

The lease grants you access to the decrypted credential value for 30 minutes. After that, the lease expires and you would need to create a new one.

List credentials

const credentials = await vault.credentials.list();

for (const cred of credentials) {
  console.log(`${cred.name} (${cred.type}) - ${cred.state}`);
}

Listing credentials does not return their values. It returns metadata, types, states, and policies.

Renew a lease

If you need more time with a credential, renew the lease before it expires:

await vault.leases.renew({
  leaseId: lease.id,
  ttl: '15m',
});

Revoke a lease

When you are done with a credential and want to release it immediately:

await vault.leases.revoke({
  leaseId: lease.id,
});

Error handling

The SDK throws typed errors for common failure cases:

import { VaultError, LeaseExpiredError, CredentialNotFoundError } from '@ghoststack/vault-sdk';

try {
  const lease = await vault.leases.create({
    credentialName: 'nonexistent-key',
    ttl: '30m',
  });
} catch (error) {
  if (error instanceof CredentialNotFoundError) {
    console.error('Credential does not exist:', error.credentialName);
  } else if (error instanceof VaultError) {
    console.error('Vault error:', error.message, error.code);
  }
}

Next steps