Skip to main content

​
Overview

Antigravity Claude Proxy supports optional API key authentication for the /v1/* endpoints. By default, authentication is disabled and the proxy uses its own configured Google accounts.

​
Default Behavior (No Auth)

When API key authentication is not configured:
  • All /v1/* endpoints are publicly accessible
  • The proxy uses its own pool of Google accounts
  • No Authorization header is required
curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-5-thinking", "messages": [...]}'

​
Enabling API Key Authentication

To secure your proxy, set the API_KEY environment variable or configure it in config.json:

​
Environment Variable

export API_KEY="your-secret-api-key"
npm start

​
Config File

Edit ~/.config/antigravity-proxy/config.json: 
{
  "apiKey": "your-secret-api-key"
}
Store your API key securely. Do not commit it to version control.

​
Using the API Key

Once authentication is enabled, include the API key in every request using the Authorization header: 
curl -X POST http://localhost:8080/v1/messages \
  -H "Authorization: Bearer your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-5-thinking", "messages": [...]}'

​
X-API-Key Header

Alternatively, use the X-API-Key header: 
curl -X POST http://localhost:8080/v1/messages \
  -H "X-API-Key: your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-5-thinking", "messages": [...]}'

​
Claude Code Integration

When using Claude Code CLI, set the ANTHROPIC_AUTH_TOKEN environment variable: 
export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_AUTH_TOKEN="your-secret-api-key"
Or configure via ~/.claude/settings.json: 
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8080",
    "ANTHROPIC_AUTH_TOKEN": "your-secret-api-key"
  }
}
If authentication is disabled on the proxy, you can use any value for ANTHROPIC_AUTH_TOKEN (e.g., "test").

​
Error Responses

​
401 Unauthorized - Missing API Key

Returned when API key is required but not provided: 
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid or missing API key"
  }
}

​
401 Unauthorized - Invalid API Key

Returned when the provided API key does not match: 
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid or missing API key"
  }
}

​
Security Best Practices

​
1. Use Strong API Keys

Generate a random API key using: 
openssl rand -base64 32

​
2. Rotate Keys Regularly

Update your API key periodically: 
# Generate new key
export NEW_API_KEY=$(openssl rand -base64 32)

# Update config
echo '{"apiKey": "'$NEW_API_KEY'"}' > ~/.config/antigravity-proxy/config.json

# Restart server
npm start

​
3. Use HTTPS in Production

For production deployments, run the proxy behind a reverse proxy with HTTPS: 
server {
  listen 443 ssl;
  server_name proxy.example.com;

  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;

  location / {
    proxy_pass http://localhost:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

​
4. Web UI Password Protection

The Web UI supports optional password protection via the WEBUI_PASSWORD environment variable: 
export WEBUI_PASSWORD="admin-password"
npm start
Clients must include the password via:
  • Header: X-WebUI-Password: admin-password
  • Query param: ?password=admin-password
WebUI password protection is separate from API key authentication. You can enable one or both.

​
Account Authentication

The proxy uses Google OAuth to authenticate with Google accounts:
  • Accounts are added via the Web UI or CLI (npm run accounts:add)
  • OAuth tokens are stored in ~/.config/antigravity-proxy/accounts.json
  • Tokens are automatically refreshed when expired
See the Account Management guide for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us