curl Quickstart

Acest ghid vă ghidează prin autentificarea la API VaultPAM și realizarea primei solicitări folosind curl.

Condiții preliminare:

• curl instalat (versiunea 7.58 sau mai nouă)
• jq instalat (pentru analiza răspunsurilor JSON — opțional dar recomandat)
• Un cont VaultPAM cu acces API activat

---

Pasul 1 — Setați URL-ul de bază

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

Înlocuiți valoarea cu URL-ul de control-plane VaultPAM real dacă utilizați o implementare auto-găzduită.

---

Pasul 2 — Autentificație

# Citiți acreditările în mod securizat — nu ștergem niciodată tokenurile în controlul sursei (consultați 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}\"}")

# Extrageți tokenul de acces
VAULTPAM_TOKEN=$(echo "${RESPONSE}" | jq -r '.access_token')
echo "Authenticated. Token expires in $(echo "${RESPONSE}" | jq '.expires_in') seconds."

Nu ștergem niciodată tokenurile

Stocați VAULTPAM_TOKEN într-o variabilă de mediu sau în managerul de secrete — nu-l codificați niciodată în scripturi. Consultați Token Storage.

---

Pasul 3 — Obțineți organizația activă

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

---

Pasul 4 — Listați safes-urile dvs.

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

Un răspuns reușit returnează o matrice JSON de obiecte safe.

---

Gestionarea erorilor

curl --fail-with-body iese cu un cod diferit de zero la răspunsurile HTTP 4xx/5xx și tipărește corpul răspunsului. Includețiți apelurile dvs. în verificări de erori:

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

Codurile de stare comune:

Cod	Semnificație
401 Unauthorized	Tokenul lipsește, a expirat sau este nevalid. Reautentificați-vă.
403 Forbidden	Tokenul nu dispune de scopul necesar pentru acest endpoint.
429 Too Many Requests	Limita de tarif depășită. Verificați antetul retry-after.
500 Internal Server Error	Eroare tranzitorie a serverului. Reîncercați cu backoff.

---

Conștientizarea limitei de tarif

Verificați antetele răspunsului pentru a monitoriza bugetu dvs.:

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"

Consultați Rate Limits pentru detalii cu privire la strategiile de backoff.

---

Pași următori

• Authentication Flow — ciclul de viață complet al tokenului, PAT-uri și stocare securizată
• Python Quickstart — același flux folosind Python
• TypeScript Quickstart — același flux folosind Node.js
• Rate Limits — înțelegeți antetele x-ratelimit-*