Authentication Guide

Learn how to set up and manage API keys for secure access to the Zoneweaver Agent.

Overview

The Zoneweaver Agent uses Bearer token authentication with API keys. All requests must include a valid API key in the Authorization header.

API Key Format

Zoneweaver Agent keys use the following format:

hw_[random_string]

Example: hw_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Getting Your First API Key

Bootstrap Method (First Install)

On a fresh installation, use the bootstrap endpoint to generate your first API key:

curl -X POST https://your-server:5001/api-keys/bootstrap \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Initial Setup",
    "description": "Bootstrap API key for initial configuration"
  }'

Response:

{
  "api_key": "hw_abc123def456...",
  "entity_id": 1,
  "name": "Initial Setup",
  "description": "Bootstrap API key for initial configuration",
  "message": "API key generated successfully",
  "note": "Bootstrap endpoint will be auto-disabled for future requests"
}

⚠️ Important: The bootstrap endpoint is automatically disabled after first use for security.

Using API Keys

In HTTP Requests

Include the API key in the Authorization header:

curl -H "Authorization: Bearer hw_your_api_key_here" \
  https://your-server:5001/stats

In Frontend Applications

const apiKey = 'hw_your_api_key_here';

fetch('https://your-server:5001/zones', {
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
})
  .then(response => response.json())
  .then(data => console.log(data));

Managing API Keys

Generate Additional API Keys

Once you have your first API key, you can generate additional keys:

curl -X POST https://your-server:5001/api-keys/generate \
  -H "Authorization: Bearer hw_your_existing_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Frontend Application",
    "description": "API key for the web frontend"
  }'

List Existing API Keys

View all API keys (without exposing the actual key values):

curl -H "Authorization: Bearer hw_your_api_key" \
  https://your-server:5001/api-keys

Get Current API Key Information

Check information about the API key you’re currently using:

curl -H "Authorization: Bearer hw_your_api_key" \
  https://your-server:5001/api-keys/info

Revoke API Keys

Deactivate an API key (can be reactivated later):

curl -X PUT \
  -H "Authorization: Bearer hw_your_api_key" \
  https://your-server:5001/api-keys/1/revoke

Delete API Keys

Permanently delete an API key:

curl -X DELETE \
  -H "Authorization: Bearer hw_your_api_key" \
  https://your-server:5001/api-keys/1

Security Best Practices

1. Environment Variables

Store API keys in environment variables, not in code:

export ZONEWEAVER_API_KEY="hw_your_api_key_here"

const apiKey = process.env.ZONEWEAVER_API_KEY;

2. Different Keys for Different Uses

Create separate API keys for:

Frontend applications
Backend services
Development/testing
Administrative tasks

3. Regular Key Rotation

Periodically regenerate API keys:

Generate a new key
Update applications to use the new key
Delete or revoke the old key

4. Monitor Key Usage

Check the last_used field to identify unused keys:

curl -H "Authorization: Bearer hw_your_api_key" \
  https://your-server:5001/api-keys

Configuration Options

Configure API key behavior in /etc/zoneweaver-agent/config.yaml:

api_keys:
  # Enable/disable bootstrap endpoint
  bootstrap_enabled: true

  # Auto-disable bootstrap after first use
  bootstrap_auto_disable: true

  # API key length (characters after hw_ prefix)
  key_length: 32

  # Bcrypt hash rounds for storing keys
  hash_rounds: 12

Troubleshooting

Invalid API Key Errors

Error: 401 Unauthorized - Invalid API key

Solutions:

Verify the API key format includes hw_ prefix
Check that the key hasn’t been revoked
Ensure the Authorization header is properly formatted
Verify the key exists in the database

Bootstrap Endpoint Disabled

Error: 403 Forbidden - Bootstrap endpoint disabled