Skip to main content
Version: v1

TypeScript Quickstart

This guide walks you through authenticating to the VaultPAM API and making your first request using TypeScript and the native fetch API (Node.js 18+).

Prerequisites:

  • Node.js 18 or later (built-in fetch API)
  • TypeScript 5.x (optional — the examples also work as plain JavaScript)
  • A VaultPAM account with API access enabled

Step 1 — Set up your environment​

# Set your base URL in the environment — never hardcode in source
export VAULTPAM_BASE_URL="https://api.vaultpam.com"
export VAULTPAM_TOKEN="<your-token>"  # Never commit — see auth-flow.md#token-storage

For production integrations, load these values from a secrets manager or a .env file that is listed in .gitignore.

Step 2 — Authenticate​

const BASE_URL = process.env.VAULTPAM_BASE_URL ?? "https://api.vaultpam.com";

interface AuthResponse {
  access_token: string;
  expires_in: number;
}

async function login(email: string, password: string): Promise<AuthResponse> {
  const response = await fetch(`${BASE_URL}/api/v1/auth/login`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, password }),
  });

  if (!response.ok) {
    throw new Error(`Login failed: ${response.status} ${await response.text()}`);
  }

  return response.json() as Promise<AuthResponse>;
}

// Load credentials from environment — never commit to source control (see auth-flow.md#token-storage)
const email = process.env.VAULTPAM_EMAIL ?? "";
const password = process.env.VAULTPAM_PASSWORD ?? "";

const { access_token: token, expires_in: expiresIn } = await login(email, password);
console.log(`Authenticated. Token expires in ${expiresIn} seconds.`);
Never commit tokens

Load VAULTPAM_TOKEN from process.env or a secrets manager — never hardcode credentials. See Token Storage.

Step 3 — Get your active organization​

interface OrgMembershipsResponse {
  active_org_id: string;
  memberships: Array<{ org_id: string; role: string }>;
}

async function getActiveOrgId(token: string): Promise<string> {
  const response = await fetch(`${BASE_URL}/api/v1/org/memberships`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (!response.ok) {
    throw new Error(`Failed to get org memberships: ${response.status}`);
  }

  const data = (await response.json()) as OrgMembershipsResponse;
  return data.active_org_id;
}

const orgId = await getActiveOrgId(token);
console.log(`Active org: ${orgId}`);

Step 4 — List your safes​

interface Safe {
  id: string;
  name: string;
}

async function listSafes(token: string, orgId: string): Promise<Safe[]> {
  const response = await fetch(`${BASE_URL}/api/v1/safes`, {
    headers: {
      Authorization: `Bearer ${token}`,
      "X-Active-Org-Id": orgId,
    },
  });

  if (!response.ok) {
    throw new Error(`Failed to list safes: ${response.status} ${await response.text()}`);
  }

  return response.json() as Promise<Safe[]>;
}

const safes = await listSafes(token, orgId);
console.log(`Found ${safes.length} safe(s):`);
safes.forEach((s) => console.log(`  - ${s.name}`));

Complete example​

const BASE_URL = process.env.VAULTPAM_BASE_URL ?? "https://api.vaultpam.com";

// Load from environment — never commit to source control (see auth-flow.md#token-storage)
const email = process.env.VAULTPAM_EMAIL ?? "";
const password = process.env.VAULTPAM_PASSWORD ?? "";

async function main(): Promise<void> {
  // Step 1: Authenticate
  const loginResp = await fetch(`${BASE_URL}/api/v1/auth/login`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, password }),
  });
  if (!loginResp.ok) throw new Error(`Login failed: ${loginResp.status}`);
  const { access_token: token } = (await loginResp.json()) as { access_token: string };

  // Step 2: Get active org
  const orgResp = await fetch(`${BASE_URL}/api/v1/org/memberships`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!orgResp.ok) throw new Error(`Org lookup failed: ${orgResp.status}`);
  const { active_org_id: orgId } = (await orgResp.json()) as { active_org_id: string };

  // Step 3: List safes
  const safesResp = await fetch(`${BASE_URL}/api/v1/safes`, {
    headers: {
      Authorization: `Bearer ${token}`,
      "X-Active-Org-Id": orgId,
    },
  });
  if (!safesResp.ok) throw new Error(`Safes request failed: ${safesResp.status}`);
  const safes = (await safesResp.json()) as Array<{ id: string; name: string }>;
  console.log(`Safes (${safes.length}):`);
  safes.forEach((s) => console.log(`  ${s.name}`));
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Error handling​

All fetch calls check response.ok and throw on failure. Common status codes:

CodeMeaning
401 UnauthorizedToken is missing, expired, or invalid. Re-authenticate.
403 ForbiddenToken lacks the required scope for this endpoint.
429 Too Many RequestsRate limit exceeded. Check retry-after header.
500 Internal Server ErrorTransient server error. Retry with backoff.

Rate limit awareness​

const response = await fetch(`${BASE_URL}/api/v1/safes`, {
  headers: { Authorization: `Bearer ${token}`, "X-Active-Org-Id": orgId },
});

const remaining = response.headers.get("x-ratelimit-remaining");
console.log(`Rate limit remaining: ${remaining}`);

See Rate Limits for backoff strategies.

Next steps​