Inicio rápido de TypeScript

Esta guía le muestra cómo autenticarse en la API de VaultPAM y realizar su primera solicitud usando TypeScript y la API nativa fetch (Node.js 18+).

Requisitos previos:

• Node.js 18 o posterior (API fetch integrada)
• TypeScript 5.x (opcional — los ejemplos también funcionan como JavaScript simple)
• Una cuenta de VaultPAM con acceso a API habilitado

---

Paso 1 — Configurar su entorno

# Establezca su URL base en el entorno — nunca codifique en la fuente
export VAULTPAM_BASE_URL="https://api.vaultpam.com"
export VAULTPAM_TOKEN="<your-token>"  # Nunca confirme — vea auth-flow.md#token-storage

Para integraciones en producción, cargue estos valores desde un gestor de secretos o un archivo .env que esté incluido en .gitignore.

---

Paso 2 — Autenticar

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>;
}

// Cargue las credenciales del entorno — nunca confirme en el control de fuente (vea 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.`);

Nunca confirme tokens

Cargue VAULTPAM_TOKEN desde process.env o un gestor de secretos — nunca codifique credenciales. Vea Almacenamiento de tokens.

---

Paso 3 — Obtener su organización activa

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}`);

---

Paso 4 — Listar sus 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}`));

---

Ejemplo completo

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

// Cargue desde el entorno — nunca confirme en el control de fuente (vea auth-flow.md#token-storage)
const email = process.env.VAULTPAM_EMAIL ?? "";
const password = process.env.VAULTPAM_PASSWORD ?? "";

async function main(): Promise<void> {
  // Paso 1: Autenticar
  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 };

  // Paso 2: Obtener org activa
  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 };

  // Paso 3: Listar 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);
});

---

Manejo de errores

Todas las llamadas fetch verifican response.ok y lanzan una excepción en caso de fallo. Códigos de estado comunes:

Código	Significado
401 Unauthorized	El token falta, ha expirado o es inválido. Vuelva a autenticar.
403 Forbidden	El token carece del alcance requerido para este punto de conexión.
429 Too Many Requests	Límite de velocidad excedido. Verifique el encabezado retry-after.
500 Internal Server Error	Error transitorio del servidor. Reintente con retroceso.

---

Consideración del límite de velocidad

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}`);

Vea Límites de velocidad para estrategias de retroceso.

---

Próximos pasos

• Flujo de autenticación — ciclo de vida completo del token, PATs y almacenamiento seguro
• Inicio rápido de curl — el mismo flujo usando la línea de comandos
• Inicio rápido de Python — el mismo flujo usando Python
• Límites de velocidad — entienda los encabezados x-ratelimit-*