fail2ban-ui/docs/api.md

API reference

This is a short index for operators. The UI primarily uses these endpoints. Paths and details may evolve; treat this as a practical reference.

Authentication

• When OIDC is enabled, all /api/* endpoints (including WebSocket) require an authenticated session, except the callback endpoints.
• Callback endpoints (/api/ban, /api/unban) are authenticated using X-Callback-Secret.

Input validation

All endpoints that accept IP addresses validate them server-side using Go's net.ParseIP / net.ParseCIDR. Requests with invalid IPs receive a 400 Bad Request response. This applies to ban/unban callbacks, manual ban/unban from the dashboard, and the advanced actions test endpoint.

Common headers

• X-F2B-Server: <server-id>
  Used by the UI to select the target server in multi-server setups (where applicable).

Endpoints

Server management

• GET /api/servers -> List configured servers
• POST /api/servers -> Create or update a server
• DELETE /api/servers/:id -> Delete a server
• POST /api/servers/:id/default -> Set server as default
• POST /api/servers/:id/test -> Test server connectivity
• GET /api/ssh/keys -> List available SSH keys

Jails and configuration

• GET /api/summary -> Dashboard summary (jails, banned IPs per server)
• GET /api/jails/manage -> List jails with enabled/disabled status
• POST /api/jails/manage -> Update jail enabled/disabled state
• POST /api/jails -> Create a new jail
• DELETE /api/jails/:jail -> Delete a jail
• GET /api/jails/:jail/config -> Get jail/filter configuration
• POST /api/jails/:jail/config -> Update jail/filter configuration
• POST /api/jails/:jail/logpath/test -> Test log path accessibility
• POST /api/jails/:jail/unban/:ip -> Unban an IP from a jail
• POST /api/jails/:jail/ban/:ip -> Ban an IP in a jail

Events and analytics

• GET /api/events/bans -> List ban/unban events (paginated, filterable)
• DELETE /api/events/bans -> Delete all stored ban events
• GET /api/events/bans/stats -> Ban statistics (counts, timeseries)
• GET /api/events/bans/insights -> Ban insights (countries, top IPs, top jails)
• GET /api/threat-intel/:ip -> Query configured threat-intel provider for an IP (AlienVault OTX / AbuseIPDB)

Advanced actions

• GET /api/advanced-actions/blocks -> List permanent block records
• DELETE /api/advanced-actions/blocks -> Delete all permanent block records
• POST /api/advanced-actions/test -> Manually test block/unblock on configured integration

Settings

• GET /api/settings -> Get current application settings
• POST /api/settings -> Update application settings
• POST /api/settings/test-email -> Send a test email (Email provider)
• POST /api/settings/test-webhook -> Send a test webhook payload (Webhook provider)
• POST /api/settings/test-elasticsearch -> Index a test document (Elasticsearch provider)

The settings payload includes alert provider configuration (alertProvider, webhook, elasticsearch fields). See alert-providers.md for the full provider documentation.

Filter management

• GET /api/filters -> List available filters
• GET /api/filters/:filter/content -> Get filter file content
• POST /api/filters -> Create a new filter
• POST /api/filters/test -> Test filter regex against log lines
• DELETE /api/filters/:filter -> Delete a filter

Service control

• POST /api/fail2ban/restart -> Restart / Reloads the Fail2Ban service

Threat intelligence

• GET /api/threat-intel/:ip

Notes:

• Validates :ip server-side.
• Requires threat-intel provider enabled in settings (alienvault or abuseipdb).
• Returns 409 when provider is disabled (none).
• Uses provider+IP cache (30 minutes) and upstream 429 retry/backoff handling.
• May include X-Threat-Intel-Cache: hit|stale response header.

For full setup and behavior details, see docs/threat-intel.md.

Version

• GET /api/version -> Get running version and optional update check

WebSocket

• GET /api/ws -> WebSocket endpoint (upgrade)

The WebSocket connection streams, real-time events to the frontend:

• heartbeat -> periodic health check (~30s)
• console_log -> debug console log lines (when debug mode is enabled)
• ban_event -> real-time ban event broadcast
• unban_event -> real-time unban event broadcast

The WebSocket enforces same-origin policy via the Origin header and requires authentication when OIDC is enabled.

Callbacks (Fail2Ban actions)

• POST /api/ban -> Receive ban notification from Fail2Ban
• POST /api/unban -> Receive unban notification from Fail2Ban

Callbacks require:

• Header: X-Callback-Secret: <secret>
• JSON body fields (typical): serverId, ip, jail, hostname, failures, logs

All IPs in callback payloads are validated before processing.

After validation, the callback triggers:

1. Event storage in the database
2. WebSocket broadcast to connected clients
3. Alert dispatch to the configured provider (Email, Webhook, or Elasticsearch) if alerts are enabled and the country filter matches

Authentication routes (OIDC)

• GET /auth/login -> Initiate OIDC login flow
• GET /auth/callback -> OIDC provider callback
• GET /auth/logout -> Logout and clear session
• GET /auth/status -> Check authentication status
• GET /auth/user -> Get current user info