Démarrage rapide TypeScript

Ce guide vous accompagne dans l'authentification à l'API VaultPAM et la réalisation de votre première requête avec TypeScript et l'API native fetch (Node.js 18+).

Prérequis :

• Node.js 18 ou ultérieur (API fetch intégrée)
• TypeScript 5.x (facultatif — les exemples fonctionnent aussi en JavaScript pur)
• Un compte VaultPAM avec l'accès API activé

---

Étape 1 — Configurez votre environnement

# 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

Pour les intégrations en production, chargez ces valeurs depuis un gestionnaire de secrets ou un fichier .env répertorié dans .gitignore.

---

Étape 2 — Authentifiez-vous

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

Ne validez jamais les jetons

Chargez VAULTPAM_TOKEN depuis process.env ou un gestionnaire de secrets — ne codez jamais les identifiants en dur. Consultez Stockage des jetons.

---

Étape 3 — Récupérez votre organisation active

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

---

Étape 4 — Listez vos coffres-forts

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

---

Exemple complet

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

---

Gestion des erreurs

Tous les appels fetch vérifient response.ok et lèvent une exception en cas d'échec. Codes de statut courants :

Code	Signification
401 Unauthorized	Le jeton est manquant, expiré ou invalide. Authentifiez-vous de nouveau.
403 Forbidden	Le jeton ne dispose pas de la portée requise pour ce point de terminaison.
429 Too Many Requests	Limite de débit dépassée. Vérifiez l'en-tête retry-after.
500 Internal Server Error	Erreur serveur transitoire. Réessayez avec un délai d'attente progressif.

---

Prise en compte des limites de débit

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

Consultez Limites de débit pour les stratégies de délai d'attente progressif.

---

Étapes suivantes

• Flux d'authentification — cycle de vie complet des jetons, PAT et stockage sécurisé
• Démarrage rapide curl — le même flux en ligne de commande
• Démarrage rapide Python — le même flux avec Python
• Limites de débit — comprendre les en-têtes x-ratelimit-*