Zum Hauptinhalt springen
Version: v1

curl Quickstart

This guide walks you through authenticating to the VaultPAM API and making your first request using curl.

Prerequisites:

  • curl installed (version 7.58 or later)
  • jq installed (for parsing JSON responses — optional but recommended)
  • A VaultPAM account with API access enabled

Step 1 — Set your base URL​

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

Replace the value with your actual VaultPAM control-plane URL if you are using a self-hosted deployment.

Step 2 — Authenticate​

# 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."
Never commit tokens

Store VAULTPAM_TOKEN in an environment variable or secrets manager — never hardcode it in scripts. See Token Storage.

Step 3 — Get your active organization​

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

Step 4 — List your 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 '.'

A successful response returns a JSON array of safe objects.

Error handling​

curl --fail-with-body exits with a non-zero code on HTTP 4xx/5xx responses and prints the response body. Wrap your calls in error checks:

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

Common status codes:

CodeMeaning
401 UnauthorizedToken is missing, expired, or invalid. Re-authenticate.
403 ForbiddenToken lacks the required scope for this endpoint.
429 Too Many RequestsRate limit exceeded. Check retry-after header.
500 Internal Server ErrorTransient server error. Retry with backoff.

Rate limit awareness​

Check the response headers to monitor your 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"

See Rate Limits for details on backoff strategies.

Next steps​