Szybki start z curl

Ten przewodnik przeprowadzi Cię przez uwierzytelnianie do API VaultPAM oraz wykonanie pierwszego żądania za pomocą curl.

Wymagania wstępne:

• Zainstalowany curl (wersja 7.58 lub nowsza)
• Zainstalowany jq (do parsowania odpowiedzi JSON — opcjonalne, ale zalecane)
• Konto VaultPAM z włączonym dostępem do API

---

Krok 1 — Ustaw bazowy URL

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

Zastąp tę wartość rzeczywistym URL warstwy sterowania (control-plane) VaultPAM, jeśli korzystasz z wdrożenia self-hosted.

---

Krok 2 — Uwierzytelnij się

# 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."

Nigdy nie umieszczaj tokenów w repozytorium

Przechowuj VAULTPAM_TOKEN w zmiennej środowiskowej lub w menedżerze sekretów — nigdy nie umieszczaj go na stałe w skryptach. Zobacz Przechowywanie tokenów.

---

Krok 3 — Pobierz swoją aktywną organizację

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

---

Krok 4 — Wyświetl listę swoich sejfów

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 '.'

Pomyślna odpowiedź zwraca tablicę JSON z obiektami sejfów.

---

Obsługa błędów

curl --fail-with-body kończy się niezerowym kodem przy odpowiedziach HTTP 4xx/5xx i wypisuje treść odpowiedzi. Umieść swoje wywołania w blokach sprawdzających błędy:

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 '.'

Najczęstsze kody statusu:

Kod	Znaczenie
401 Unauthorized	Token jest brakujący, wygasł lub jest nieprawidłowy. Uwierzytelnij się ponownie.
403 Forbidden	Token nie ma wymaganego zakresu (scope) dla tego punktu końcowego.
429 Too Many Requests	Przekroczono limit żądań. Sprawdź nagłówek retry-after.
500 Internal Server Error	Przejściowy błąd serwera. Ponów próbę z wykładniczym opóźnieniem (backoff).

---

Świadomość limitów żądań

Sprawdzaj nagłówki odpowiedzi, aby monitorować swój budżet:

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"

Szczegóły dotyczące strategii ponawiania (backoff) znajdziesz w Limity żądań.

---

Następne kroki

• Przepływ uwierzytelniania — pełny cykl życia tokenu, PAT-y i bezpieczne przechowywanie
• Szybki start z Pythonem — ten sam przepływ w języku Python
• Szybki start z TypeScript — ten sam przepływ z użyciem Node.js
• Limity żądań — zrozum nagłówki x-ratelimit-*