curl Guía rápida

Esta guía le explica cómo autenticarse en la API de VaultPAM y realizar su primera solicitud usando curl.

Requisitos previos:

curl instalado (versión 7.58 o posterior)
jq instalado (para analizar respuestas JSON — opcional pero recomendado)
Una cuenta de VaultPAM con acceso a API habilitado

Paso 1 — Establezca su URL base

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

Reemplace el valor con su URL de control-plane de VaultPAM si utiliza una implementación autohospedada.

Paso 2 — Autentíquese

# Lea las credenciales de forma segura — nunca confirme tokens en el control de versiones (vea 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}\"}")

# Extraiga el token de acceso
VAULTPAM_TOKEN=$(echo "${RESPONSE}" | jq -r '.access_token')
echo "Authenticated. Token expires in $(echo "${RESPONSE}" | jq '.expires_in') seconds."

Nunca confirme tokens

Almacene VAULTPAM_TOKEN en una variable de entorno o gestor de secretos — nunca lo codifique en scripts. Vea Almacenamiento de tokens.

Paso 3 — Obtenga su organización activa

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

Paso 4 — Liste sus 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 respuesta exitosa devuelve una matriz JSON de objetos Safe.

Manejo de errores

curl --fail-with-body sale con un código no cero en respuestas HTTP 4xx/5xx e imprime el cuerpo de la respuesta. Envuelva sus llamadas en comprobaciones de error:

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

Códigos de estado comunes:

Código	Significado
`401 Unauthorized`	El token falta, ha expirado o es inválido. Vuelva a autenticarse.
`403 Forbidden`	El token carece del ámbito requerido para este punto de conexión.
`429 Too Many Requests`	Límite de velocidad excedido. Compruebe el encabezado `retry-after`.
`500 Internal Server Error`	Error transitorio del servidor. Reintente con retroceso.

Conocimiento del límite de velocidad

Compruebe los encabezados de respuesta para supervisar su presupuesto:

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"

Vea Límites de velocidad para obtener detalles sobre estrategias de retroceso.

Siguientes pasos

Flujo de autenticación — ciclo de vida completo de tokens, PATs y almacenamiento seguro
Guía rápida de Python — el mismo flujo usando Python
Guía rápida de TypeScript — el mismo flujo usando Node.js
Límites de velocidad — comprenda los encabezados x-ratelimit-*

Paso 1 — Establezca su URL base​

Paso 2 — Autentíquese​

Paso 3 — Obtenga su organización activa​

Paso 4 — Liste sus Safes​

Manejo de errores​

Conocimiento del límite de velocidad​

Siguientes pasos​