curl-Schnellstart

Diese Anleitung führt Sie durch die Authentifizierung bei der VaultPAM-API und die Durchführung Ihrer ersten Anfrage mit curl.

Voraussetzungen:

• curl installiert (Version 7.58 oder höher)
• jq installiert (zum Parsen von JSON-Antworten — optional, aber empfohlen)
• Ein VaultPAM-Konto mit aktiviertem API-Zugriff

---

Schritt 1 — Basis-URL festlegen

export VAULTPAM_BASE_URL="https://api.vaultpam.com"

Ersetzen Sie den Wert durch Ihre tatsächliche VaultPAM-Control-Plane-URL, falls Sie eine selbst gehostete Bereitstellung verwenden.

---

Schritt 2 — Authentifizieren

# Read credentials securely — never commit tokens to source control (see auth-flow.md#token-storage)
read -p "Email: " VAULTPAM_EMAIL
read -s -p "Password: " VAULTPAM_PASSWORD
echo

RESPONSE=$(curl --silent --fail-with-body \
  --url "${VAULTPAM_BASE_URL}/api/v1/auth/login" \
  --header "Content-Type: application/json" \
  --data "{\"email\": \"${VAULTPAM_EMAIL}\", \"password\": \"${VAULTPAM_PASSWORD}\"}")

# Extract the access token
VAULTPAM_TOKEN=$(echo "${RESPONSE}" | jq -r '.access_token')
echo "Authenticated. Token expires in $(echo "${RESPONSE}" | jq '.expires_in') seconds."

Tokens niemals committen

Speichern Sie VAULTPAM_TOKEN in einer Umgebungsvariablen oder einem Secrets-Manager — kodieren Sie ihn niemals fest in Skripten. Siehe Token-Speicherung.

---

Schritt 3 — Ihre aktive Organisation abrufen

ORG_RESPONSE=$(curl --silent --fail-with-body \
  --url "${VAULTPAM_BASE_URL}/api/v1/org/memberships" \
  --header "Authorization: Bearer ${VAULTPAM_TOKEN}")

VAULTPAM_ORG_ID=$(echo "${ORG_RESPONSE}" | jq -r '.active_org_id')
echo "Active org: ${VAULTPAM_ORG_ID}"

---

Schritt 4 — Ihre Safes auflisten

curl --silent --fail-with-body \
  --url "${VAULTPAM_BASE_URL}/api/v1/safes" \
  --header "Authorization: Bearer ${VAULTPAM_TOKEN}" \
  --header "X-Active-Org-Id: ${VAULTPAM_ORG_ID}" \
  | jq '.'

Eine erfolgreiche Antwort gibt ein JSON-Array von Safe-Objekten zurück.

---

Fehlerbehandlung

curl --fail-with-body beendet sich bei HTTP-4xx/5xx-Antworten mit einem Exit-Code ungleich null und gibt den Antwort-Body aus. Schließen Sie Ihre Aufrufe in Fehlerprüfungen ein:

if ! SAFES=$(curl --silent --fail-with-body \
  --url "${VAULTPAM_BASE_URL}/api/v1/safes" \
  --header "Authorization: Bearer ${VAULTPAM_TOKEN}" \
  --header "X-Active-Org-Id: ${VAULTPAM_ORG_ID}"); then
  echo "Request failed: ${SAFES}" >&2
  exit 1
fi
echo "${SAFES}" | jq '.'

Häufige Statuscodes:

Code	Bedeutung
401 Unauthorized	Token fehlt, ist abgelaufen oder ungültig. Erneut authentifizieren.
403 Forbidden	Token verfügt nicht über den erforderlichen Scope für diesen Endpunkt.
429 Too Many Requests	Ratenlimit überschritten. Prüfen Sie den retry-after-Header.
500 Internal Server Error	Vorübergehender Serverfehler. Mit Backoff erneut versuchen.

---

Ratenlimit-Bewusstsein

Prüfen Sie die Antwort-Header, um Ihr Budget zu überwachen:

curl --silent --fail-with-body --include \
  --url "${VAULTPAM_BASE_URL}/api/v1/safes" \
  --header "Authorization: Bearer ${VAULTPAM_TOKEN}" \
  --header "X-Active-Org-Id: ${VAULTPAM_ORG_ID}" \
  | grep -i "x-ratelimit"

Weitere Informationen zu Backoff-Strategien finden Sie unter Ratenlimits.

---

Nächste Schritte

• Authentifizierungsablauf — vollständiger Token-Lebenszyklus, PATs und sichere Speicherung
• Python-Schnellstart — derselbe Ablauf mit Python
• TypeScript-Schnellstart — derselbe Ablauf mit Node.js
• Ratenlimits — verstehen Sie die x-ratelimit-*-Header