Shadow APIs are the silent killers of perimeter security. In FastAPI, developers often hide dangerous internal endpoints from Swagger/OpenAPI documentation using 'include_in_schema=False', mistakenly believing that 'out of sight' means 'out of reach'. To a researcher, these hidden routes are high-value targets. Real security requires explicit authentication, authorization, and network isolation, not just hiding the documentation.

The Vulnerable Pattern

from fastapi import FastAPI
app = FastAPI()
VULNERABLE: Hidden from docs but accessible to anyone who guesses the URL
@app.get(“/api/v1/debug/dump-env”, include_in_schema=False)
async def dump_environment():
return {“database_url”: “postgresql://admin:secret@db:5432/prod”, “api_key”: “sk_live_512345”}

The Secure Implementation

To kill shadow APIs, follow these rules: 1. Never rely on 'include_in_schema=False' for security; it only removes the route from the UI, not the router. 2. Implement mandatory Dependency Injection for all 'internal' routes to enforce AuthN/AuthZ. 3. Use separate FastAPI sub-applications for internal management tools and bind them to different ports or internal-only interfaces. 4. Use a centralized API Gateway to block any traffic to paths not explicitly whitelisted in your public contract.

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import APIKeyHeader
import os
app = FastAPI()
INTERNAL_TOKEN = os.getenv(“INTERNAL_ADMIN_TOKEN”)
api_key_header = APIKeyHeader(name=“X-Internal-Secret”)
async def validate_internal_access(token: str = Depends(api_key_header)):
if token != INTERNAL_TOKEN:
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=“Access Denied”)
SECURE: Explicitly documented (or not), but strictly protected by dependency injection
@app.get(“/api/v1/admin/config”, dependencies=[Depends(validate_internal_access)])
async def get_config():
return {“status”: “authorized”, “config”: ”…”}