AdminSite

The AdminSite is the central registry for models and custom admin pages. It mirrors Django’s AdminSite pattern.

Default site

A global site instance is exported from the package:

from fastapi_mongo_admin import site, ModelAdmin

site.register(Product, ProductAdmin)

Custom AdminSite

Create a dedicated site for branding, template overrides, or multi-tenant apps:

from pathlib import Path
from fastapi_mongo_admin import AdminSite

class EcommerceAdminSite(AdminSite):
    site_header = "Ecommerce Admin"
    site_title = "Shop Manager"
    index_title = "Store administration"

admin_site = EcommerceAdminSite(template_dirs=[Path("myapp/templates")])

Branding attributes

Attribute	Default	Used in
`site_header`	`"FastAPI Mongo Admin"`	Page header on all admin pages
`site_title`	`"Admin"`	Browser title suffix
`index_title`	`"Site administration"`	Admin index page heading

Registering models

Single model

site.register(Product, ProductAdmin)

Multiple models with the same admin class

site.register([Category, Brand], CatalogAdmin)

Inline options

Pass options as keyword arguments to override ModelAdmin attributes:

site.register(
    Product,
    ProductAdmin,
    list_display=["name", "price"],
    list_per_page=50,
)

collection_name is required — either on the ModelAdmin class or as a registration option. Duplicate collection names raise ValueError.

Registering custom views

Add pages outside the standard CRUD flow:

from fastapi import Request
from fastapi.responses import HTMLResponse

async def reports(request: Request) -> HTMLResponse:
    return HTMLResponse("<h1>Reports</h1>")

site.register_view("Reports", "/reports/", reports)

The view is mounted at /admin/reports/ (relative to your router prefix). An optional permission callable can gate access:

def staff_only(request: Request, user) -> bool:
    return bool(user and user.get("is_staff"))

site.register_view("Reports", "/reports/", reports, permission=staff_only)

Template directories

Override bundled templates by registering a search path:

from pathlib import Path

site = AdminSite(template_dirs=[Path("myapp/templates")])

Jinja2 resolves templates from your directories before the package defaults. See Template Customization for override patterns.

CSRF tokens

When your FastAPI app uses SessionMiddleware, the admin reads a csrf_token from the session and includes it in forms. Mutating requests (POST add/change/delete/action) verify the token automatically.

from starlette.middleware.sessions import SessionMiddleware

app.add_middleware(SessionMiddleware, secret_key="your-secret-key")

See API Reference for the full AdminSite API.