REST API

KoreShield's REST API contract is generated from the live FastAPI app.

• Interactive docs (Swagger UI): GET /docs
• ReDoc: GET /redoc
• OpenAPI JSON: GET /openapi.json

Authentication Model

Protected endpoints require authentication via one of these methods:

1. Authorization: Bearer <jwt> - JWT issued via the dashboard login
2. X-API-Key: ks_... - API key provisioned via the dashboard
3. ks_access_token httpOnly cookie - JWT set during login

JWT validation is strict:

• issuer (iss) is required and verified
• audience (aud) is required and verified
• expiry (exp) and issued-at (iat) are verified
• key policy enforces either HS256 secret mode or RS256 keypair mode

Core Endpoint Groups

Health & Monitoring

Endpoint	Method	Auth	Description
/health	GET	None	Basic health check
/health/providers	GET	None	Per-provider health status
/status	GET	None	Full status with statistics and provider info
/metrics	GET	None	Prometheus-format metrics

Security Proxy

Endpoint	Method	Auth	Description
/v1/chat/completions	POST	Required	OpenAI-compatible chat endpoint with security scanning
/v1/rag/scan	POST	Required	RAG context scanning for indirect injection
/v1/scan	POST	Required	Scan a single prompt or message
/v1/scan/batch	POST	Required	Scan multiple inputs in one request
/v1/scans	GET	Required	List recent scan results
/v1/scans/{scan_id}	GET	Required	Fetch a single scan result

All protected proxy endpoints are rate-limited via SlowAPI (default: 60/minute, configurable via security.rate_limit in config).

Analytics & Reports

Endpoint	Method	Auth	Description
/v1/analytics/*	Various	Required	Usage and security analytics
/v1/reports/*	Various	Required	Generate and download reports

WebSocket

/ws/events provides real-time event streaming for dashboards and monitoring.

Auth via:

• Header: Authorization: Bearer <jwt>
• Cookie: ks_access_token

note

WebSocket endpoints are not part of the OpenAPI document, as OpenAPI does not describe WebSocket handlers in this framework.

Rate Limiting

All protected proxy endpoints use rate limits. The default limit can be adjusted in your dashboard settings (hosted) or deployment configuration (self-hosted).