vw-api/README.md

Vaultwarden API Proxy

A secure, lightweight Go API that acts as a proxy between your local apps and Vaultwarden (self-hosted Bitwarden server). Use it as a replacement for .env files in development and production environments.

Features

• Secure: API key authentication, HTTPS-ready, constant-time comparison, no sensitive logging
• Lightweight: ~15MB Docker image, minimal resource usage
• Fast: Built-in caching with configurable TTL
• Simple: Clean architecture, easy to deploy and maintain
• Production-ready: Rate limiting, health checks, graceful shutdown, security headers

Architecture

┌─────────────┐     HTTPS + API Key     ┌──────────────────┐
│  Your App   │ ───────────────────────> │ Vaultwarden API  │
└─────────────┘                          │     Proxy        │
                                         └──────────────────┘
                                                  │
                                                  │ Vaultwarden API
                                                  ▼
                                         ┌──────────────────┐
                                         │  Vaultwarden     │
                                         │    Server        │
                                         └──────────────────┘

Project Structure

.
├── cmd/
│   └── api/
│       └── main.go              # Application entry point
├── internal/
│   ├── auth/
│   │   └── middleware.go        # API key authentication
│   ├── config/
│   │   └── config.go           # Configuration management
│   ├── handlers/
│   │   └── handlers.go         # HTTP handlers
│   └── vaultwarden/
│       └── client.go           # Vaultwarden API client
├── pkg/
│   └── logger/
│       └── logger.go           # Secure logging
├── .env.example                # Environment variables template
├── .gitignore                  # Git ignore rules
├── Dockerfile                  # Multi-stage Docker build
├── docker-compose.yml          # Docker Compose configuration
├── go.mod                      # Go module definition
├── go.sum                      # Go module checksums
├── Makefile                    # Build automation
└── README.md                   # This file

Quick Start

Prerequisites

• Go 1.25+ (for local development)
• Docker & Docker Compose (for containerized deployment)
• Vaultwarden instance with API access

Local Development

1. Clone the repository

   git clone https://github.com/thijsherman/vaultwarden-api.git
   cd vaultwarden-api
   

2. Create environment file

   cp .env.example .env
   

3. Configure your .env file

   # Generate a strong API key
   make generate-api-key
   
   # Edit .env and add:
   # - API_KEY (generated above)
   # - VAULTWARDEN_URL (your Vaultwarden instance URL)
   # - VAULTWARDEN_ACCESS_TOKEN (from Vaultwarden settings)
   

4. Run the application

   make run
   

Docker Deployment

1. Build the Docker image

   make docker-build
   

2. Run with Docker Compose

   make docker-compose-up
   

API Endpoints

Health Check

curl http://localhost:8080/health

Response:

{
  "status": "ok",
  "service": "vaultwarden-api"
}

Get Secret

curl -H "Authorization: Bearer YOUR_API_KEY" \
     http://localhost:8080/secret/DATABASE_URL

Response:

{
  "name": "DATABASE_URL",
  "value": "postgresql://user:pass@localhost:5432/db"
}

Refresh Cache

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     http://localhost:8080/refresh

Response:

{
  "status": "ok",
  "message": "cache cleared successfully"
}

Configuration

All configuration is done via environment variables:

Variable	Required	Default	Description
API_PORT	No	8080	Port the API listens on
ENVIRONMENT	No	development	Environment (development/production)
API_KEY	Yes	-	API key for authentication
VAULTWARDEN_URL	Yes	-	Vaultwarden instance URL
VAULTWARDEN_ACCESS_TOKEN	Yes	-	Vaultwarden API access token
CACHE_TTL	No	5m	Cache duration (0 to disable)
READ_TIMEOUT	No	10s	HTTP read timeout
WRITE_TIMEOUT	No	10s	HTTP write timeout

Getting Vaultwarden Access Token

There are several ways to get an access token for Vaultwarden:

1. Via Web UI (if available):

   • Log into Vaultwarden
   • Go to Settings → Security
   • Generate a new API Key

2. Via CLI (for self-hosted):

   • Use the Vaultwarden CLI or API to generate a token
   • Refer to Vaultwarden documentation for your specific version

3. Via Personal Access Token:

   • Some Vaultwarden versions support personal access tokens
   • Check your instance's API documentation

Deployment Guide

Deploy to Portainer

1. Prepare your environment

   • Ensure Vaultwarden is accessible from the Portainer host
   • Have your API credentials ready

2. Create a new Stack in Portainer

   • Navigate to Stacks → Add Stack
   • Name it vaultwarden-api
   • Paste the contents of docker-compose.yml

3. Set environment variables in Portainer

   • Click "Add environment variable"
   • Add all required variables (see Configuration table)
   • IMPORTANT: Never hardcode secrets in the stack file

4. Deploy the stack

   • Click "Deploy the stack"
   • Monitor logs for any errors

5. Set up reverse proxy

   • Use Nginx Proxy Manager, Traefik, or similar
   • Configure HTTPS with Let's Encrypt
   • Point to vaultwarden-api:8080

Deploy Behind Nginx Proxy Manager

1. Add a new Proxy Host

   • Domain: api.yourdomain.com
   • Forward to: vaultwarden-api:8080
   • Enable "Block Common Exploits"
   • Enable "Websockets Support"

2. Configure SSL

   • Request a new SSL certificate (Let's Encrypt)
   • Force SSL
   • Enable HTTP/2

3. Add custom headers (optional)

   X-Real-IP $remote_addr
   X-Forwarded-For $proxy_add_x_forwarded_for
   X-Forwarded-Proto $scheme
   

Security Best Practices

For Public Repositories

• ✅ Use .env.example (committed) for documentation
• ✅ Add .env to .gitignore (already done)
• ✅ Never commit actual credentials
• ✅ Use Portainer's environment variable feature
• ✅ Rotate API keys regularly
• ✅ Use strong, randomly generated API keys

For Private Repositories

• ✅ Still use .env.example for documentation
• ✅ Still never commit .env files
• ✅ Use secret managers (e.g., Docker secrets, Vault)
• ✅ Implement additional authentication if needed
• ✅ Monitor access logs

Production Deployment

1. Always use HTTPS via reverse proxy
2. Restrict CORS to specific domains (edit main.go)
3. Set ENVIRONMENT=production in .env
4. Enable rate limiting (already configured)
5. Use read-only filesystem (already in docker-compose)
6. Run as non-root user (already in Dockerfile)
7. Monitor logs for suspicious activity
8. Implement IP whitelisting if possible
9. Use Docker secrets instead of environment variables
10. Regular security updates (rebuild images monthly)

Usage Examples

From a Shell Script

#!/bin/bash

API_KEY="your-api-key"
API_URL="https://api.yourdomain.com"

# Fetch database URL
DB_URL=$(curl -s -H "Authorization: Bearer $API_KEY" \
  "$API_URL/secret/DATABASE_URL" | jq -r '.value')

echo "Database URL: $DB_URL"

From Python

import requests

API_KEY = "your-api-key"
API_URL = "https://api.yourdomain.com"

def get_secret(name):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    response = requests.get(f"{API_URL}/secret/{name}", headers=headers)
    return response.json()["value"]

# Usage
db_url = get_secret("DATABASE_URL")
print(f"Database URL: {db_url}")

From Node.js

const axios = require('axios');

const API_KEY = 'your-api-key';
const API_URL = 'https://api.yourdomain.com';

async function getSecret(name) {
  const response = await axios.get(`${API_URL}/secret/${name}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  return response.data.value;
}

// Usage
(async () => {
  const dbUrl = await getSecret('DATABASE_URL');
  console.log(`Database URL: ${dbUrl}`);
})();

Makefile Commands

make help              # Show available commands
make build             # Build the binary
make run              # Run locally (requires .env)
make dev              # Run with hot reload
make test             # Run tests
make clean            # Clean build artifacts
make docker-build     # Build Docker image
make docker-run       # Run Docker container
make docker-push      # Push to Docker Hub
make generate-api-key # Generate a random API key

Troubleshooting

"Failed to load configuration: API_KEY is required"

• Make sure you have a .env file in the project root
• Copy .env.example to .env and fill in all required values

"Secret not found"

• Verify the secret name matches exactly (case-sensitive)
• Check that your Vaultwarden token has access to the vault
• Use the Vaultwarden web UI to confirm the secret exists

"Vaultwarden api returned status 401"

• Your VAULTWARDEN_ACCESS_TOKEN is invalid or expired
• Generate a new token from Vaultwarden settings

Docker build fails

• Ensure you have the latest Go version in Dockerfile
• Run go mod tidy before building
• Check for network issues when downloading dependencies

Future Enhancements

• Support for multiple Vaultwarden instances
• JWT-based authentication (in addition to API keys)
• Token rotation mechanism
• Metrics and monitoring (Prometheus)
• Support for secret versioning
• Webhook notifications for secret changes
• Redis-based distributed cache
• Rate limiting per API key
• Audit logging
• GraphQL API

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

Disclaimer

This is a security-sensitive tool. Please:

• Review the code before deploying to production
• Keep your API keys and tokens secure
• Monitor access logs regularly
• Report security issues privately

Support

For issues and questions:

• Open an issue on GitHub
• Check existing issues for solutions
• Provide detailed error messages and logs

---

Built with ❤️ using Go and Fiber