Γρήγορη Εκκίνηση TypeScript

Αυτός ο οδηγός σας καθοδηγεί στην πιστοποίηση στο VaultPAM API και στη δημιουργία του πρώτου σας αιτήματος χρησιμοποιώντας TypeScript και το εγγενές fetch API (Node.js 18+).

Προαπαιτούμενα:

• Node.js 18 ή νεότερη έκδοση (ενσωματωμένο fetch API)
• TypeScript 5.x (προαιρετικό — τα παραδείγματα λειτουργούν επίσης ως απλό JavaScript)
• Ένας λογαριασμός VaultPAM με ενεργοποιημένη πρόσβαση API

---

Βήμα 1 — Ρύθμιση του περιβάλλοντός σας

# Ορίστε τη βασική διεύθυνση URL στο περιβάλλον — ποτέ μη σκληρoκωδικοποιήσετε στο source
export VAULTPAM_BASE_URL="https://api.vaultpam.com"
export VAULTPAM_TOKEN="<your-token>"  # Ποτέ μη κάνετε commit — δείτε auth-flow.md#token-storage

Για παραγωγικές ενσωματώσεις, φορτώστε αυτές τις τιμές από έναν διαχειριστή μυστικών ή ένα αρχείο .env που περιλαμβάνεται στο .gitignore.

---

Βήμα 2 — Πιστοποίηση

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

// Φορτώστε τα διαπιστευτήρια από το περιβάλλον — ποτέ μη κάνετε commit στο source control (δείτε 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.`);

Ποτέ μη κάνετε commit tokens

Φορτώστε VAULTPAM_TOKEN από process.env ή από έναν διαχειριστή μυστικών — ποτέ μη σκληρoκωδικοποιήσετε διαπιστευτήρια. Δείτε Αποθήκευση Token.

---

Βήμα 3 — Λάβετε τη δραστική οργάνωσή σας

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

---

Βήμα 4 — Παράταξη των 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}`));

---

Ολοκληρωμένο παράδειγμα

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

// Φορτώστε από το περιβάλλον — ποτέ μη κάνετε commit στο source control (δείτε auth-flow.md#token-storage)
const email = process.env.VAULTPAM_EMAIL ?? "";
const password = process.env.VAULTPAM_PASSWORD ?? "";

async function main(): Promise<void> {
  // Βήμα 1: Πιστοποίηση
  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 };

  // Βήμα 2: Λήψη δραστικής 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 };

  // Βήμα 3: Παράταξη 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);
});

---

Διαχείριση σφαλμάτων

Όλες οι κλήσεις fetch ελέγχουν response.ok και ρίχνουν εξαίρεση κατά την αποτυχία. Κοινοί κωδικοί κατάστασης:

Κωδικός	Σημασία
401 Unauthorized	Το token λείπει, έχει λήξει ή είναι μη έγκυρο. Επαναπιστοποιηθείτε.
403 Forbidden	Το token δεν έχει το απαιτούμενο scope για αυτό το endpoint.
429 Too Many Requests	Το όριο ρυθμού έχει ξεπεραστεί. Ελέγξτε την κεφαλίδα retry-after.
500 Internal Server Error	Παροδικό σφάλμα διακομιστή. Δοκιμάστε ξανά με backoff.

---

Συνειδητοποίηση ορίου ρυθμού

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

Δείτε Όρια ρυθμού για στρατηγικές backoff.

---

Επόμενα βήματα

• Authentication Flow — πλήρης κύκλος ζωής token, PATs και ασφαλής αποθήκευση
• curl Quickstart — ίδια ροή χρησιμοποιώντας τη γραμμή εντολών
• Python Quickstart — ίδια ροή χρησιμοποιώντας Python
• Rate Limits — κατανοήστε τις κεφαλίδες x-ratelimit-*