Security & API Scopes

HoloBridge provides granular access control through API scopes, allowing you to create API keys with limited permissions.

API Key Configuration

Single Key (Simple)

For basic setups, use a single API key in .env:

API_KEY=your_secure_api_key

This key has admin scope (full access).

Multiple Keys with Scopes

For production, define multiple keys with specific permissions using the API_KEYS environment variable:

API_KEYS=[
  {"id":"dashboard","name":"Web Dashboard","key":"dash_xxx","scopes":["read:guilds","read:members"]},
  {"id":"bot","name":"Chat Bot","key":"bot_xxx","scopes":["read:messages","write:messages"]},
  {"id":"admin","name":"Admin Panel","key":"admin_xxx","scopes":["admin"]}
]

Available Scopes

Scope	Permissions
read:guilds	List guilds, get guild details
read:channels	List channels, get channel info
read:members	List members, get member details
read:messages	Read message history
write:messages	Send, edit, delete messages
write:members	Kick, ban, timeout members
write:channels	Create, edit, delete channels
write:roles	Create, edit, delete roles
events	Subscribe to WebSocket events
admin	Full access (bypasses all checks)

Rate Limiting

HoloBridge includes built-in rate limiting to protect against abuse.

Configuration

RATE_LIMIT_ENABLED=true
RATE_LIMIT_WINDOW_MS=60000  # 1 minute window
RATE_LIMIT_MAX=100          # 100 requests per window

Response Headers

All API responses include rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when limit resets

Rate Limited Response

When the limit is exceeded, you'll receive:

{
  "success": false,
  "error": "Too many requests",
  "code": "RATE_LIMITED",
  "retryAfter": 45
}

Next Steps