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

Navigation: Home | Getting Started | API Reference | WebSocket | Plugins | Security | Network

• API Key Configuration
• Available Scopes
• Rate Limiting
• Best Practices

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

API_KEY=your_secure_api_key

This key has admin scope (full access).

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"]}
]

Each API key object has the following properties:

Read-only dashboard:

{"id":"dashboard","name":"Dashboard","key":"dash_xxx","scopes":["read:guilds","read:channels","read:members"]}

Message bot:

{"id":"msgbot","name":"Message Bot","key":"msg_xxx","scopes":["read:messages","write:messages"]}

Moderation bot:

{"id":"modbot","name":"Mod Bot","key":"mod_xxx","scopes":["read:members","write:members"]}

WebSocket listener:

{"id":"listener","name":"Event Listener","key":"ws_xxx","scopes":["events","read:guilds"]}

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

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

All API responses include rate limit headers:

When the limit is exceeded, you'll receive a 429 Too Many Requests response:

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

The retryAfter field indicates how many seconds to wait before retrying.

1. Use scoped keys — Give each integration only the permissions it needs
2. Rotate keys regularly — Update API keys periodically
3. Keep admin keys secure — Only use admin scope for trusted applications
4. Never commit keys — Add .env to .gitignore
5. Use environment variables — Don't hardcode keys in your application

When exposing the API on your network (see Network Configuration):

1. Always require authentication — Never disable the API_KEY requirement
2. Use scoped keys for remote access — Create specific keys for each client device
3. Monitor usage — Watch rate limit headers to identify issues
4. Use HTTPS in production — Consider using a reverse proxy with TLS

# Main admin key (local use only)
API_KEY=admin_super_secret_key

# Scoped keys for different clients
API_KEYS=[
  {"id":"web-dashboard","name":"Web Dashboard","key":"web_abc123","scopes":["read:guilds","read:channels","read:members","events"]},
  {"id":"mobile-app","name":"Mobile App","key":"mob_def456","scopes":["read:guilds","read:messages"]},
  {"id":"bot-service","name":"Bot Service","key":"bot_ghi789","scopes":["read:messages","write:messages","events"]},
  {"id":"admin-cli","name":"Admin CLI","key":"cli_jkl012","scopes":["admin"]}
]

• Log API key usage (which key accessed what endpoint)
• Set up alerts for rate limit violations
• Review and revoke unused keys periodically
• Use unique keys per integration for better tracking

Missing or invalid API key:

{
    "success": false,
    "error": "API key required",
    "code": "UNAUTHORIZED"
}

Solution: Include the X-API-Key header with a valid key.

API key lacks required scope:

{
    "success": false,
    "error": "Insufficient permissions",
    "code": "FORBIDDEN"
}

Solution: Use an API key with the required scope, or add the scope to the existing key.

• Getting Started - Initial setup and configuration
• API Reference - Explore all available REST API endpoints
• Network Configuration - Expose the API on your local network
• Plugins - Create plugins with custom endpoints