Does FastAPI Work With Payload CMS?
FastAPI and Payload CMS can work together as separate services (FastAPI frontend consuming Payload's REST API), but they don't integrate directly since Payload is TypeScript-based and FastAPI is Python.
Quick Facts
How FastAPI Works With Payload CMS
FastAPI and Payload CMS operate best as decoupled services in a headless architecture. Payload runs as your content management backend (Node.js/TypeScript), exposing REST and GraphQL APIs, while FastAPI serves as your Python-based application layer or separate API service. FastAPI consumes Payload's API endpoints using httpx or requests to fetch content, manage users, or handle webhooks. This separation is actually ideal for microservices architectures—you get Payload's excellent TypeScript admin UI and content modeling while leveraging FastAPI's Python ecosystem (data science, ML integration, async performance). The developer experience is straightforward: define your content schema in Payload, auto-generate OpenAPI docs in FastAPI, and communicate via standard HTTP. The main consideration is managing authentication across services (Payload JWT tokens need to be validated in FastAPI) and handling eventual consistency if both systems manage state. For simple use cases like a blog backend, this is overkill; for complex applications needing Python-specific features alongside professional CMS capabilities, it's a powerful combination.
Best Use Cases
FastAPI consuming Payload CMS REST API
pip install fastapi uvicorn httpx python-dotenvfrom fastapi import FastAPI, Depends
from fastapi.responses import JSONResponse
import httpx
from typing import Optional
app = FastAPI()
PAYLOAD_URL = "http://localhost:3000/api"
PAYLOAD_SECRET = "your-api-key"
async def get_payload_client():
async with httpx.AsyncClient(headers={
"Authorization": f"JWT {PAYLOAD_SECRET}"
}) as client:
yield client
@app.get("/posts")
async def get_posts(client: httpx.AsyncClient = Depends(get_payload_client)):
response = await client.get(f"{PAYLOAD_URL}/posts")
return response.json()
@app.get("/posts/{post_id}")
async def get_post(post_id: str, client: httpx.AsyncClient = Depends(get_payload_client)):
response = await client.get(f"{PAYLOAD_URL}/posts/{post_id}")
return response.json()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)Known Issues & Gotchas
Authentication mismatch: Payload uses JWT tokens that FastAPI doesn't automatically understand
Fix: Validate Payload JWT in FastAPI middleware using the same secret, or implement a shared auth service. Use FastAPI's Depends() with custom auth logic.
Cross-origin requests: Running Payload and FastAPI on different ports during development causes CORS issues
Fix: Configure CORS in both services explicitly. In FastAPI, use CORSMiddleware. In Payload, set cors in config.
Webhook delivery reliability: Payload webhooks to FastAPI can fail silently if FastAPI is down
Fix: Implement exponential backoff retry logic in Payload webhooks or use a queue system (Redis, RabbitMQ) between services.
Rate limiting across service boundaries: Hard to enforce global rate limits when Payload and FastAPI are separate
Fix: Use API gateway (Kong, Traefik) or implement shared rate limiting via Redis.
Alternatives
- •Next.js + Payload CMS: Simpler setup if you want TypeScript throughout; Payload has native Next.js integration
- •Django + Payload CMS: More batteries-included Python framework with built-in admin, but heavier than FastAPI
- •Express.js + Payload CMS: Stay in Node.js ecosystem entirely, avoid cross-language complexity
Resources
Related Compatibility Guides
Explore more compatibility guides