Skip to main content

​
Overview

OpenFang supports optional Bearer token authentication for securing API access. When enabled, all requests must include a valid API key.

​
Configuration

Set the API key in ~/.openfang/config.toml: 
api_key = "your-secret-key-here"
Important: If api_key is empty or not set, authentication is disabled and all requests are accepted. This is convenient for local development but insecure for production.

​
Authentication Methods

OpenFang accepts API keys via two methods: Include the API key as a Bearer token: 
curl -H "Authorization: Bearer your-secret-key-here" \
  http://127.0.0.1:4200/api/agents

​
2. X-API-Key Header (Alternative)

For clients that can’t set Authorization headers: 
curl -H "X-API-Key: your-secret-key-here" \
  http://127.0.0.1:4200/api/agents

​
Security Features

​
Constant-Time Comparison

API key validation uses constant-time comparison via subtle::ConstantTimeEq to prevent timing attacks: 
token.as_bytes().ct_eq(api_key.as_bytes()).into()

​
Loopback Exemption

Requests from 127.0.0.1 or ::1 bypass authentication when API key is set, allowing local CLI access: 
if addr.ip().is_loopback() {
    return Ok(next.run(req).await);
}
This means you can use openfang CLI commands locally without needing to pass the API key, even when authentication is enabled.

​
Error Responses

When authentication fails, the API returns: Status Code: 401 Unauthorized Headers: 
WWW-Authenticate: Bearer
Body: 
{
  "error": "Missing Authorization: Bearer <api_key> header"
}

​
WebSocket Authentication

WebSocket connections (/api/agents/{id}/ws) also support Bearer authentication: 
const ws = new WebSocket('ws://127.0.0.1:4200/api/agents/abc123/ws');

// Send auth token in first message
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'your-secret-key-here'
  }));
};
Alternatively, pass the token as a query parameter: 
const ws = new WebSocket('ws://127.0.0.1:4200/api/agents/abc123/ws?token=your-secret-key-here');

​
Rate Limiting

Authenticated requests are subject to the same rate limits as unauthenticated requests:
  • 30 requests/second per IP (default)
  • Configurable via GCRA rate limiter
See API Overview for details.

​
Best Practices

Use Strong Keys

Generate API keys with at least 32 bytes of entropy:
openssl rand -base64 32

Rotate Regularly

Change API keys periodically and after any suspected compromise

HTTPS in Production

Always use HTTPS when exposing the API over a network

Environment Variables

Store API keys in environment variables, not in code:
export OPENFANG_API_KEY="..."

​
Signed Manifests

For enhanced security when spawning agents, OpenFang supports Ed25519-signed manifests: 
curl -X POST http://127.0.0.1:4200/api/agents \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "manifest_toml": "name = \"trusted-agent\"\n...",
    "signed_manifest": "{\"manifest\":\"...\",\"signature\":\"...\"}"
  }'
The kernel verifies the Ed25519 signature before spawning the agent. Signature verification failures return 403 Forbidden.

​
Audit Trail

All authentication events are logged to the audit trail: 
curl http://127.0.0.1:4200/api/audit/recent

[
  {
    "actor": "127.0.0.1",
    "action": "AuthAttempt",
    "resource": "api_key",
    "details": "success",
    "timestamp": "2025-03-06T12:00:00Z"
  }
]

​
Next Steps

Agents API

Start making authenticated requests to spawn and manage agents