Admin

Every admin-wide setting (such as the navbar title, the mount location, CSRF and authentication configurations, and the rendered theme) is passed as a keyword argument to the Admin class.

Basic usage

To get started, import the Admin class from the contrib package that matches your Object-Relational Mapper (ORM):

from starlette_admin.contrib.sqla import Admin  # SQLAlchemy
from starlette_admin.contrib.sqlmodel import Admin  # SQLModel
from starlette_admin.contrib.beanie import Admin  # Beanie
from starlette_admin.contrib.mongoengine import Admin  # MongoEngine
from starlette_admin.contrib.tortoise import Admin  # Tortoise ORM

Here is a minimal configuration using SQLAlchemy:

from sqlalchemy import create_engine
from starlette.applications import Starlette
from starlette_admin.contrib.sqla import Admin, ModelView

from myapp.models import Post

engine = create_engine("sqlite:///admin.sqlite")
app = Starlette()

admin = Admin(
    session_provider=engine,
    title="My Admin",
    base_url="/admin",
    secret_key="a-long-random-string",
)
admin.add_view(ModelView(Post))
admin.mount_to(app)

• The title parameter sets the navbar text and the HTML <title> tag.
• The base_url defines the path prefix where the admin is mounted.
• The secret_key signs the CSRF and flash cookies.
• The add_view method registers a view, while mount_to builds the admin's routes and middleware before mounting them onto your application.

Every Admin class accepts all the configuration options documented below and occasionally adds backend-specific functionality:

• contrib.sqla.Admin(session_provider, ...) requires an Engine, AsyncEngine, sessionmaker, or async_sessionmaker as its first positional argument and automatically inserts DBSessionMiddleware. Note that contrib.sqlmodel.Admin is simply this same class re-exported. See SQLAlchemy and SQLModel.
• contrib.beanie.Admin, contrib.mongoengine.Admin, and contrib.tortoise.Admin take no extra constructor arguments because Beanie, MongoEngine, and Tortoise ORM manage their own connections outside the admin interface. Additionally, mongoengine.Admin registers a GridFS file-serving route within mount_to. See Beanie, MongoEngine, and Tortoise ORM.

Full reference

All parameters listed below are accepted as keyword arguments by the Admin constructor.

Identity and branding

The logo_url, login_logo_url, and favicon_url parameters accept either a string or a (request) -> str | None callable. Using a callable is particularly useful when different requests (such as different hostnames or a multi-tenant application) require dynamic branding:

def logo_for_tenant(request):
    return f"https://cdn.example.com/{request.state.tenant}/logo.png"


admin = Admin(engine, title="My Admin", logo_url=logo_for_tenant)

Mounting

Running more than one Admin within the same application requires a distinct base_url and route_name for each instance. Otherwise, generated links from one admin might incorrectly resolve to another. See Multiple Admin Instances.

Templates, statics, and theme

These options are covered in full in Custom Themes and Templates.

The home page

The default is a welcome banner alongside one panel per registered model view, displaying its respective record count. To replace this, pass your own CustomView (typically a DefaultIndexView subclass or any CustomView featuring a widget). For further instructions, see Custom Views & Widgets.

Auth, security, and data safety

All five parameters are covered in depth in the Security documentation.

Locale and timezone

For a complete walkthrough, refer to Internationalization & Timezones.

Debugging

admin = Admin(
    session_provider=engine, title="My Admin", secret_key="a-long-random-string", debug=True
)

This is highly useful during development. Every request logs the executed middleware, the view that resolved a given URL, and the reasoning behind a passed or failed permission check. Keep this disabled in production; it is verbose and adds significant logging overhead to every request.

For a lighter approach, call starlette_admin.logging.configure_logging(level=logging.INFO) manually instead of passing debug=True. This provides the handler without the complete DEBUG verbosity.

Registering Views and Mounting

After creating the Admin instance, you must register your views and mount the admin interface to your application.

admin.add_view(ModelView(Post))  # Register a view (e.g., BaseModelView, CustomView)
admin.mount_to(app)  # Mount the admin onto your Starlette or FastAPI app

Registering Views

Use add_view to add components to your admin dashboard. This method accepts either a view instance or a view class. You can use it to register model views, custom pages, drop-down menus, and external links.

Mounting the Application

Once you have registered all your views, call mount_to(app) exactly once to attach the admin to your Starlette or FastAPI application. This step finalizes your routing and security configurations.

Order of operations is critical. The admin configuration is locked once mounted to ensure all views are properly routed.

• Accessing the underlying admin.app before mounting raises a RuntimeError.
• Attempting to register additional views or calling mount_to again after the initial mount also raises a RuntimeError.

admin.app  # Raises RuntimeError: not mounted yet

admin.mount_to(app)
admin.app  # Returns the mounted sub-application

admin.add_view(ModelView(Comment))  # Raises RuntimeError: already mounted

What's next

• Security: The secret_key, CSRF, and complete export/import limits.
• Authentication: Wiring up the auth_provider.
• Multiple Admin Instances: Running more than one Admin in the same application.