curl Avvio rapido

Questa guida ti accompagna nell'autenticazione all'API VaultPAM e nella creazione della tua prima richiesta utilizzando curl.

Prerequisiti:

• curl installato (versione 7.58 o successiva)
• jq installato (per l'analisi delle risposte JSON — facoltativo ma consigliato)
• Un account VaultPAM con accesso API abilitato

---

Passaggio 1 — Imposta l'URL di base

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

Sostituisci il valore con l'URL effettivo del tuo control-plane VaultPAM se stai utilizzando una distribuzione self-hosted.

---

Passaggio 2 — Autentica

# Leggi le credenziali in modo sicuro — non committere mai i token nel controllo del codice sorgente (vedi 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}\"}")

# Estrai il token di accesso
VAULTPAM_TOKEN=$(echo "${RESPONSE}" | jq -r '.access_token')
echo "Autenticato. Token scade tra $(echo "${RESPONSE}" | jq '.expires_in') secondi."

Non committere mai i token

Archivia VAULTPAM_TOKEN in una variabile d'ambiente o in un gestore di segreti — non codificarlo mai in script. Vedi Archiviazione token.

---

Passaggio 3 — Ottieni la tua organizzazione attiva

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 "Org attiva: ${VAULTPAM_ORG_ID}"

---

Passaggio 4 — Elenca i tuoi 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}" \
  | jq '.'

Una risposta riuscita restituisce un array JSON di oggetti safe.

---

Gestione degli errori

curl --fail-with-body esce con un codice diverso da zero su risposte HTTP 4xx/5xx e stampa il corpo della risposta. Avvolgi le tue chiamate in controlli di errore:

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 "Richiesta non riuscita: ${SAFES}" >&2
  exit 1
fi
echo "${SAFES}" | jq '.'

Codici di stato comuni:

Codice	Significato
401 Unauthorized	Il token è assente, scaduto o non valido. Effettua nuovamente l'autenticazione.
403 Forbidden	Il token non dispone dell'ambito richiesto per questo endpoint.
429 Too Many Requests	Limite di velocità superato. Controlla l'intestazione retry-after.
500 Internal Server Error	Errore transitorio del server. Riprova con backoff.

---

Consapevolezza del limite di velocità

Controlla le intestazioni della risposta per monitorare il tuo budget:

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"

Vedi Limiti di velocità per i dettagli sulle strategie di backoff.

---

Passaggi successivi

• Flusso di autenticazione — ciclo di vita completo del token, PAT e archiviazione sicura
• Avvio rapido Python — lo stesso flusso utilizzando Python
• Avvio rapido TypeScript — lo stesso flusso utilizzando Node.js
• Limiti di velocità — comprendi le intestazioni x-ratelimit-*