Ghid de pornire rapidă TypeScript

Acest ghid vă conduce prin procesul de autentificare la API-ul VaultPAM și realizarea primei solicitări folosind TypeScript și API-ul nativ fetch (Node.js 18+).

Condiții prealabile:

• Node.js 18 sau mai recent (API fetch încorporat)
• TypeScript 5.x (opțional — exemplele funcționează și ca JavaScript simplu)
• Un cont VaultPAM cu acces API activat

---

Pasul 1 — Configurați-vă mediul

# Setați adresa URL de bază în mediu — nu codificați în sursă
export VAULTPAM_BASE_URL="https://api.vaultpam.com"
export VAULTPAM_TOKEN="<your-token>"  # Nu vă angajați — vezi auth-flow.md#token-storage

Pentru integrări în producție, încărcați aceste valori de la un manager de secrete sau dintr-un fișier .env care este listat în .gitignore.

---

Pasul 2 — Autentificați-vă

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

// Încărcați acreditările din mediu — nu vă angajați la controlul surselor (vezi 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.`);

Nu vă angajați token-uri

Încărcați VAULTPAM_TOKEN din process.env sau un manager de secrete — nu codificați niciodată acreditările. Vezi Stocarea token-urilor.

---

Pasul 3 — Preluați organizația dvs. activă

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

---

Pasul 4 — Listați safes-ul dvs.

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

---

Exemplu complet

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

// Încărcați din mediu — nu vă angajați la controlul surselor (vezi auth-flow.md#token-storage)
const email = process.env.VAULTPAM_EMAIL ?? "";
const password = process.env.VAULTPAM_PASSWORD ?? "";

async function main(): Promise<void> {
  // Pasul 1: Autentificați-vă
  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 };

  // Pasul 2: Preluați organizația activă
  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 };

  // Pasul 3: Listați safes-ul
  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);
});

---

Gestionarea erorilor

Toate apelurile fetch verifică response.ok și aruncă la eșec. Coduri de stare frecvente:

Cod	Semnificație
401 Unauthorized	Token-ul lipsește, a expirat sau este invalid. Re-autentificați-vă.
403 Forbidden	Token-ul nu dispune de domeniul de aplicare necesar pentru acest endpoint.
429 Too Many Requests	Limita de rate depășită. Verificați header-ul retry-after.
500 Internal Server Error	Eroare tranzitorie a serverului. Reîncercați cu backoff.

---

Conștientizarea limitei de rate

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

Consultați Limite de rate pentru strategii de backoff.

---

Pași următori

• Flux de autentificare — ciclu complet de token, PATs și stocare sigură
• Ghid de pornire rapidă curl — același flux folosind linia de comandă
• Ghid de pornire rapidă Python — același flux folosind Python
• Limite de rate — înțelegeți header-urile x-ratelimit-*