How to Use EnvVault

EnvVault is a secure API for storing and retrieving secrets, credentials, and environment variables. This guide focuses on using EnvVault via API and command-line tools.

🔑 Your API Key

All API requests require authentication using your API key. You can find your API key in the Dashboard under "API Keys".

💡 Tip: Store your EnvVault API key in a secure location (password manager, environment variable, or secure file). Never commit it to version control.

🔐 Session Tokens with Email 2FA (For AI Tools)

⚠️ Never give your master API key to AI tools like Claude or ChatGPT! Instead, create temporary session tokens that automatically expire. When SMTP email is configured, session creation is protected by two-factor authentication (2FA) — a 6-digit verification code is sent to your email.

Why Session Tokens?

  • 2FA Protected: Email verification code required to create tokens (when SMTP is configured)
  • Short-lived: Expire after 24 hours (default) — max 7 days
  • Scoped: Restrict to specific applications (e.g., only "claude" application)
  • Revocable: Instantly revoke if leaked or no longer needed
  • Safe: If leaked in chat logs, attacker has limited time + access
  • Non-admin: Cannot create users, manage API keys, or access admin functions

How Email 2FA Works

When you create a session token via the API, EnvVault sends a 6-digit verification code to your registered email address. You must enter this code within 5 minutes to complete the session creation. This ensures that even if your master API key is compromised, an attacker cannot create session tokens without access to your email.

💡 Note: If SMTP email is not configured on your EnvVault instance, 2FA is skipped and session tokens are created directly. Site admins can also bypass 2FA for testing/automation by passing "skip_2fa": true in the request body.

Creating Session Tokens (Two-Step 2FA Flow)

Via API (with 2FA)

# Step 1: Initiate — sends a 6-digit code to your email
curl -X POST https://envvault.fly.dev/api/v1/sessions \
  -H "Authorization: Bearer YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl_seconds": 86400,
    "role": "write",
    "applications": ["claude"],
    "description": "Claude Code session"
  }'
# Response: {
#   "verification_id": "a1b2c3d4-...",
#   "code_expires_in_minutes": 5,
#   "email_sent_to": "you@example.com"
# }

# Step 2: Verify — enter the code from your email
curl -X POST https://envvault.fly.dev/api/v1/sessions/verify \
  -H "Content-Type: application/json" \
  -d '{
    "verification_id": "a1b2c3d4-...",
    "code": "482951"
  }'
# Response: {
#   "session_token": "sess_abc123...",
#   "session": {"id": 1, "role": "write", ...}
# }

Via Dashboard

  1. Click "+ New Session Token" in the Active Sessions card
  2. Choose duration: 1 hour to 7 days (default: 24 hours)
  3. Choose permissions: Read-only, Read+Write, or Admin
  4. Optionally restrict to specific applications (e.g., claude, development)
  5. Add a description to identify the session later
  6. Check your email for the 6-digit verification code
  7. Enter the code to complete creation
  8. Copy the session token (shown only once!)

Via CLI (bypasses 2FA)

# CLI creates session tokens directly (no email verification needed)
python -m envvault.cli create-session \
  --username yourname \
  --ttl-hours 24 \
  --role write \
  --applications claude \
  --description "Claude Code session"

Using Session Tokens with Claude

# After creating a session token (via API 2FA or CLI):
# Give the session token to Claude (safe to paste in chat)

# Claude uses it to fetch secrets:
curl https://envvault.fly.dev/api/v1/variables/OPENAI_API_KEY?application=claude \
  -H "Authorization: Bearer sess_abc123..."

# Token expires automatically after 24 hours!

Application Scoping Example

Create a dedicated application for AI tools to prevent access to production secrets: 

# Store AI-related keys in the "claude" application
curl -X POST https://envvault.fly.dev/api/v1/variables \
  -H "Authorization: Bearer YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OPENAI_API_KEY",
    "value": "sk-proj-...",
    "application": "claude",
    "description": "OpenAI key for Claude Code"
  }'

# Create session token ONLY for "claude" application (via 2FA)
# Now Claude can access OPENAI_API_KEY but NOT production secrets!

Best Practices

  • Configure SMTP email for 2FA protection on session creation
  • Create a new session token for each AI session (daily or per-project)
  • Use application scoping to isolate sensitive secrets
  • Set appropriate TTL (1h for experiments, 24h for daily work)
  • Revoke unused sessions from the dashboard
  • Never share your master API key — only session tokens!
  • Use "Revoke All Sessions" immediately if your master key is compromised

📦 Storing Secrets

Use the POST /api/v1/variables endpoint to store secrets:

curl -X POST https://envvault.fly.dev/api/v1/variables \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OPENAI_API_KEY",
    "value": "sk-proj-...",
    "application": "production",
    "description": "OpenAI API key for production"
  }'

Applications

Organize your secrets by application or project, such as myapp, backend, or claude. This keeps your secrets organized and prevents accidental misuse. You can also set an optional environment field (e.g., production, staging) on each variable.

🔍 Retrieving Secrets

Fetch a single secret by name:

curl https://envvault.fly.dev/api/v1/variables/OPENAI_API_KEY?application=production \
  -H "Authorization: Bearer YOUR_API_KEY"

Extract Just the Value

Use jq to extract just the secret value:

# In your terminal
export OPENAI_API_KEY=$(curl -s https://envvault.fly.dev/api/v1/variables/OPENAI_API_KEY?application=production \
  -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.value')

echo $OPENAI_API_KEY

📋 List All Secrets

View metadata for all your secrets (values are NOT returned):

curl https://envvault.fly.dev/api/v1/variables?application=production \
  -H "Authorization: Bearer YOUR_API_KEY"

🎯 Bulk Retrieval

Fetch multiple secrets in a single request for better performance:

curl -X POST https://envvault.fly.dev/api/v1/variables/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "names": ["DATABASE_URL", "OPENAI_API_KEY", "STRIPE_SECRET"],
    "application": "production"
  }'

🤖 Using with AI Services (Claude, ChatGPT, etc.)

EnvVault is perfect for AI coding assistants that need access to your API keys. Here's how to integrate it:

Option 1: Shell Integration (Recommended)

Add this to your ~/.bashrc or ~/.zshrc:

# Store your EnvVault API key
export ENVVAULT_API_KEY="your-envvault-api-key-here"

# Function to fetch secrets from EnvVault
envvault() {
  local name=$1
  local app=${2:-default}
  curl -s "https://envvault.fly.dev/api/v1/variables/$name?application=$app" \
    -H "Authorization: Bearer $ENVVAULT_API_KEY" | jq -r '.value'
}

# Auto-load common secrets
export OPENAI_API_KEY=$(envvault OPENAI_API_KEY production)
export ANTHROPIC_API_KEY=$(envvault ANTHROPIC_API_KEY production)

Option 2: Direct API Calls

For one-off usage or in scripts:

# Fetch and use immediately
API_KEY=$(curl -s https://envvault.fly.dev/api/v1/variables/GITHUB_TOKEN?application=production \
  -H "Authorization: Bearer $ENVVAULT_API_KEY" | jq -r '.value')

# Use in your command
gh auth login --with-token <<< "$API_KEY"

Option 3: Claude Code Integration

If using Claude Code CLI, you can configure it to fetch secrets automatically:

# In your project's .env file or shell profile
export OPENAI_API_KEY=$(curl -s https://envvault.fly.dev/api/v1/variables/OPENAI_API_KEY \
  -H "Authorization: Bearer $ENVVAULT_API_KEY" | jq -r '.value')

# Now Claude Code can use the API key
claude-code "Write me a script using OpenAI"

🗑️ Deleting Secrets

Remove a secret you no longer need:

curl -X DELETE https://envvault.fly.dev/api/v1/variables/OLD_API_KEY?application=staging \
  -H "Authorization: Bearer YOUR_API_KEY"

🔐 Security Best Practices

  • Configure SMTP email to enable 2FA on session token creation
  • Use session tokens (not master keys) for AI tools and automation
  • Use separate applications to isolate secrets per project or service
  • Create read-only API keys for CI/CD pipelines
  • Rotate your API keys regularly
  • Never log or print secret values in production
  • Use HTTPS for all API requests (required)
  • Store your EnvVault API key securely (never commit to git)
  • Revoke all sessions immediately if your master key is compromised

📖 Common Use Cases

CI/CD Pipeline

# In your .github/workflows/deploy.yml
env:
  ENVVAULT_API_KEY: ${{ secrets.ENVVAULT_API_KEY }}

steps:
  - name: Fetch production secrets
    run: |
      export DATABASE_URL=$(curl -s https://envvault.fly.dev/api/v1/variables/DATABASE_URL?application=production \
        -H "Authorization: Bearer $ENVVAULT_API_KEY" | jq -r '.value')
      echo "::add-mask::$DATABASE_URL"
      echo "DATABASE_URL=$DATABASE_URL" >> $GITHUB_ENV

Docker Container

# In your Dockerfile entrypoint script
#!/bin/bash
export DATABASE_URL=$(curl -s https://envvault.fly.dev/api/v1/variables/DATABASE_URL \
  -H "Authorization: Bearer $ENVVAULT_API_KEY" | jq -r '.value')

# Start your application with secrets loaded
exec "$@"

Development Environment

# Create a .env.local file (gitignored)
#!/bin/bash
# fetch-secrets.sh

curl -X POST https://envvault.fly.dev/api/v1/variables/bulk \
  -H "Authorization: Bearer $ENVVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names": ["DATABASE_URL", "REDIS_URL", "STRIPE_KEY"], "application": "development"}' \
  | jq -r '.variables | to_entries | .[] | "\(.key)=\(.value)"' > .env.local

❓ Need Help?

If you have questions or run into issues, check the GitHub repository or contact your administrator.

Back to Dashboard