Flaxon 0.3.0 and Teloce-Py 0.3.0 are available on PyPI. Release instructions are maintained on this site; source links identify the framework snapshot. Check version and upgrade guidance.

Admin API Reference

For generated projects, use the shared settings.py, Flaxon.from_settings(), explicit mounts in app.py, and management.py workflow. See ORM and project management for Python migrations, model registration, permission hooks, relationship editing, and Admin/CMS metadata storage. Backend-only and legacy adapter examples remain supported.

Admin Dashboard

AdminDashboard(self, app: Any, config: AdminConfig | None=None, url_prefix: str='/admin', template_dir: str | None=None, registry: Registry | None=None, users: list[dict[str, Any]] | None=None, auth_backend: Any | None=None, upload_dir: str='uploads', store: AdminStore | None=None, storage_path: str | None=None, redis_url: str | None=None, database: Any | None=None, password_reset_sender: Any | None=None, email_verification_sender: Any | None=None, require_email_verification: bool=False, max_upload_size: int=10 * 1024 * 1024, allowed_upload_types: set[str] | None=None, media_storage: Any | None=None, redis_protocol: int=2, redis_max_connections: int=100, thumbnail_sync_limit: int=2 * 1024 * 1024, session_idle_timeout: int | None=None, media_scanner: Any | None=None, media_retention_days: int=365, webauthn_provider: Any | None=None, permission_provider: AuthorizationProvider | None=None, strict_permissions: bool=False, max_image_dimensions: tuple[int, int]=(10000, 10000), password_hasher: PasswordHasher | None=None, microservices: bool | dict[str, Any]=True, cookie_secure: bool | None=None, session_bound_csrf: bool=False)

Admin dashboard implementation for the admin subsystem.

View implementation

Public methods and properties

`register`

def register(self, model: Any, **options: Any) -> None

`register_widget`

def register_widget(self, widget: Any) -> Any

`register_permission`

def register_permission(self, key: str, label: str, category: str='Custom', description: str='', *, dangerous: bool=False) -> Any

`permission_for_action`

def permission_for_action(self, model_name: str, action: str) -> str

Return and lazily register a model action capability.

`add_view`

def add_view(self, view: Any, name: str, *, url: str | None=None, category: str='Custom', icon: str='fa-puzzle-piece', methods: set[str] | None=None, permission: str='admin.view_dashboard') -> Any

The page is protected by permission before the callback runs. The callback may still perform additional object-level authorization.

`mount_module`

def mount_module(self, module: Any, *, prefix: str | None=None, name: str | None=None, navigation: list[dict[str, Any]] | None=None) -> Any

Mount a normal :class:FlaxonModule as an Admin extension.

The module keeps its own routes, hooks, templates, static assets and dependencies. Admin only supplies the mount boundary and optional navigation metadata, so extension code does not need to reach into Admin internals or query another service's database.

`add_hook`

def add_hook(self, name: str, callback: Any) -> Any

Add the hook.

`run_hook`

def run_hook(self, name: str, value: Any) -> Any

Perform the run hook operation for admin dashboard.

`unregister`

def unregister(self, model: Any) -> None

Unregister a model from the dashboard's registry.

`navigation_user`

def navigation_user(self)

Current request's staff identity, including views with sparse contexts.

`can_access_model`

def can_access_model(self, user: Any, model_name: str, action: str='read') -> bool

Return whether a template or extension may show a model action.

`index`

async def index(self, request: Request) -> Response

Perform the index operation for admin dashboard.

`list_view`

async def list_view(self, request: Request, model_name: str) -> Response

Render the list page for the current request.

`model_add_view`

async def model_add_view(self, request: Request, model_name: str) -> Response

Render the model add page for the current request.

`detail_view`

async def detail_view(self, request: Request, model_name: str, object_id: str) -> Response

Render the detail page for the current request.

`edit_view`

async def edit_view(self, request: Request, model_name: str, object_id: str) -> Response

Render the edit page for the current request.

`delete_view`

async def delete_view(self, request: Request, model_name: str, object_id: str) -> Response

Render the delete page for the current request.

`model_action`

async def model_action(self, request: Request, model_name: str, action_name: str) -> Response

Perform the model action operation for admin dashboard.

`record_activity`

def record_activity(self, action: str, resource: str, request: Request, record_id: str | None=None, **details: Any) -> None

Record the activity.

`csrf_token`

def csrf_token(self) -> str

Perform the csrf token operation for admin dashboard.

`validate_csrf`

def validate_csrf(self, data: dict[str, Any]) -> dict[str, Any]

Validate the csrf.

`login`

async def login(self, request: Request) -> Response

Establish an authenticated session for the supplied credentials.

`logout`

async def logout(self, request: Request) -> Response

End the current authenticated session.

`password_reset`

async def password_reset(self, request: Request) -> Response

Perform the password reset operation for admin dashboard.

`verify_email`

async def verify_email(self, request: Request) -> Response

Verify the email.

`profile`

async def profile(self, request: Request) -> Response

Perform the profile operation for admin dashboard.

`users_view`

async def users_view(self, request: Request) -> Response

Render the users page for the current request.

`roles_view`

async def roles_view(self, request: Request) -> Response

Render the roles page for the current request.

`user_api`

async def user_api(self, request: Request, username: str) -> Response

Perform the user api operation for admin dashboard.

`media_view`

async def media_view(self, request: Request) -> Response

Render the media page for the current request.

`resumable_media`

async def resumable_media(self, request: Request, upload_id: str | None=None) -> Response

Perform the resumable media operation for admin dashboard.

`media_folders_api`

async def media_folders_api(self, request: Request) -> Response

Perform the media folders api operation for admin dashboard.

`media_bulk_api`

async def media_bulk_api(self, request: Request) -> Response

Apply an explicit action to selected media records.

`media_signed_url`

async def media_signed_url(self, request: Request, filename: str) -> Response

Perform the media signed url operation for admin dashboard.

`media_api`

async def media_api(self, request: Request, filename: str) -> Response

Perform the media api operation for admin dashboard.

`search`

async def search(self, request: Request) -> Response

Perform the search operation for admin dashboard.

`relationship_choices`

async def relationship_choices(self, request: Request, model_name: str, field_name: str) -> Response

Perform the relationship choices operation for admin dashboard.

`model_export`

async def model_export(self, request: Request, model_name: str) -> Response

Perform the model export operation for admin dashboard.

`model_import`

async def model_import(self, request: Request, model_name: str) -> Response

Validate an import, enforce model permissions, and report transaction outcomes.

`settings_view`

async def settings_view(self, request: Request) -> Response

Render the settings page for the current request.

`history`

async def history(self, request: Request, model_name: str, object_id: str) -> Response

Perform the history operation for admin dashboard.

`activity_view`

async def activity_view(self, request: Request) -> Response

Render the activity page for the current request.

`activity_export`

async def activity_export(self, request: Request) -> Response

Perform the activity export operation for admin dashboard.

`notifications_api`

async def notifications_api(self, request: Request) -> Response

Return and update durable per-user admin notifications.

`notification_preferences`

async def notification_preferences(self, request: Request) -> Response

Perform the notification preferences operation for admin dashboard.

`audit_verify`

async def audit_verify(self, request: Request) -> Response

Perform the audit verify operation for admin dashboard.

`webauthn_api`

async def webauthn_api(self, request: Request) -> Response

Perform the webauthn api operation for admin dashboard.

`trusted_devices_api`

async def trusted_devices_api(self, request: Request, device_id: str | None=None) -> Response

Perform the trusted devices api operation for admin dashboard.

`mfa_recovery_api`

async def mfa_recovery_api(self, request: Request) -> Response

Perform the mfa recovery api operation for admin dashboard.

`operations_view`

async def operations_view(self, request: Request) -> Response

Render the operations page for the current request.

`operations_tasks_api`

async def operations_tasks_api(self, request: Request) -> Response

Perform the operations tasks api operation for admin dashboard.

`get_urls`

def get_urls(self) -> list[tuple[str, str, Any]]

Return the urls.

Admin Configuration

AdminConfig(self, site_title: str='Flaxon Admin', site_header: str='Flaxon Administration', index_title: str='Welcome to Flaxon Admin', enable_dark_mode: bool=True, enable_search: bool=True, enable_actions: bool=True, enable_filters: bool=True, enable_pagination: bool=True, logo_url: str | None=None, custom_styles: str | None=None, custom_scripts: str | None=None, timezone: str='UTC', settings: dict[str, Any] | None=None)

Admin config implementation for the admin subsystem.

View implementation

Public methods and properties

`to_dict`

def to_dict(self) -> dict[str, Any]

Return a dictionary representation of the current value.

Registry

Registry(self)

Registry implementation for the admin subsystem.

View implementation

Public methods and properties

`register`

def register(self, model: Any, **options: Any) -> None

Perform the register operation for registry.

`unregister`

def unregister(self, model: Any) -> None

Perform the unregister operation for registry.

`get`

def get(self, name: str) -> AdminModel | None

Retrieve the requested value using this object's configured behavior.

`get_by_model`

def get_by_model(self, model: Any) -> AdminModel | None

Return the by model.

`get_all`

def get_all(self) -> list[AdminModel]

Return all matching stored entries.

`clear`

def clear(self) -> None

Remove the stored entries.

Admin Model

AdminModel(self, model: Any, *, list_display: list[str] | None=None, list_filter: list[str] | None=None, search_fields: list[str] | None=None, fields: list[str] | None=None, readonly_fields: list[str] | None=None, ordering: list[str] | None=None, name: str | None=None, icon: str | None=None, actions: dict[str, Any] | list[Any] | tuple[Any, ...] | None=None, can_view: Any | None=None, can_add: Any | None=None, can_change: Any | None=None, can_delete: Any | None=None, validate_import: Any | None=None, queryset: Any | None=None, fieldsets: dict[str, list[str]] | None=None, widgets: dict[str, str] | None=None, inlines: dict[str, Any] | None=None)

Admin model implementation for the admin subsystem.

View implementation

Public methods and properties

`get_name`

def get_name(self) -> str

Return the name.

`get_verbose_name`

def get_verbose_name(self) -> str

Return the verbose name.

`get_verbose_name_plural`

def get_verbose_name_plural(self) -> str

Return the verbose name plural.

`add_action`

def add_action(self, name: str, func: Any) -> None

Add the action.

`get_actions`

def get_actions(self) -> dict[str, Any]

Return the actions.

`get_permission_hook`

def get_permission_hook(self, action: str) -> Any | None

Return the permission hook.

`display_value`

def display_value(obj: Any, field: Any) -> Any

Resolve a list column like Flask-Admin's column_formatters.

Admin Views

Base View

AdminView(self, admin_model: Any, request: Request, dashboard: Any)

Admin view implementation for the admin subsystem.

View implementation

Public methods and properties

`invalid_form`

async def invalid_form(self, error, data, template, obj=None)

Perform the invalid form operation for admin view.

`render`

async def render(self) -> HTMLResponse | RedirectResponse

Render the requested content using the supplied context.

Change List View

class ChangeListView

Change list view implementation for the admin subsystem.

View implementation

Public methods and properties

`render`

async def render(self) -> HTMLResponse

Render the requested content using the supplied context.

Detail View

DetailView(self, admin_model: Any, request: Request, dashboard: Any, object_id: str)

Detail view implementation for the admin subsystem.

View implementation

Public methods and properties

`render`

async def render(self) -> HTMLResponse

Render the requested content using the supplied context.

Create View

class CreateView

Create view implementation for the admin subsystem.

View implementation

Public methods and properties

`render`

async def render(self) -> HTMLResponse | RedirectResponse

Render the requested content using the supplied context.

Update View

UpdateView(self, admin_model: Any, request: Request, dashboard: Any, object_id: str)

Update view implementation for the admin subsystem.

View implementation

Public methods and properties

`render`

async def render(self) -> HTMLResponse | RedirectResponse

Render the requested content using the supplied context.

Delete View

DeleteView(self, admin_model: Any, request: Request, dashboard: Any, object_id: str)

Delete view implementation for the admin subsystem.

View implementation

Public methods and properties

`render`

async def render(self) -> HTMLResponse | RedirectResponse

Render the requested content using the supplied context.

Decorators

admin_model

def admin_model(**options: Any) -> Callable[[type], type]

Decorator to register a model class with the default admin registry.

View implementation

admin_action

def admin_action(name: str | None=None) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Decorator to mark a function or method as an admin bulk action.

View implementation

admin_display

def admin_display(header: str | None=None) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Decorator to mark a method as a custom column display in admin views.

View implementation

Exceptions

AdminError

class AdminError

Report a admin failure.

View implementation

ModelNotFoundError

class ModelNotFoundError

Report a model not found failure.

View implementation

PermissionDeniedError

class PermissionDeniedError

Report a permission denied failure.

View implementation

ValidationError

class ValidationError

Report a validation failure.

View implementation

Production Services

These services are available for durable Admin integrations:

from flaxon.admin import (
    DurableJobStore, DurableJobWorker, ImmutableAuditLog,
    NotificationService, ResumableUploadStore, WebAuthnService,
)

Service	Purpose
`DurableJobStore`	Persist queued, running, completed, and failed jobs with retry metadata.
`DurableJobWorker`	Register named handlers and process due jobs.
`ImmutableAuditLog`	Append hash-chained records and verify tamper evidence.
`NotificationService`	Store preferences and per-user channel delivery records.
`ResumableUploadStore`	Persist upload sessions, chunks, and final SHA-256 validation.
`WebAuthnService`	Delegate registration and assertion ceremonies to an injected provider.

HTTP Endpoints

Method	Path	Description
`POST`	`/admin/media/resumable`	Create a resumable upload session.
`GET`	`/admin/media/resumable/{upload_id}`	Read the current upload offset and expiry.
`PATCH`	`/admin/media/resumable/{upload_id}`	Upload a raw byte chunk using `Upload-Offset`.
`POST`	`/admin/media/resumable/{upload_id}/complete`	Validate and persist the completed upload.
`GET`	`/admin/media/folders`	List configured media folders.
`POST`	`/admin/media/folders`	Create a media folder with a CSRF header.
`DELETE`	`/admin/media/folders/{folder}`	Delete a folder and its stored files.
`POST`	`/admin/media/bulk`	Delete selected media names with a CSRF header.
`PATCH`	`/admin/media/{filename}`	Rename an asset or update allowed metadata.
`DELETE`	`/admin/media/{filename}`	Delete one asset with a CSRF header.
`GET`	`/admin/media/{filename}/signed-url`	Return a storage signed URL when the adapter supports it.
`GET`	`/admin/notifications/preferences`	Read the current user’s notification preferences.
`POST`	`/admin/notifications/preferences`	Update preferences with a CSRF header.
`GET`	`/admin/audit/verify`	Verify the persisted audit hash chain.
`POST`	`/admin/profile/webauthn/register/begin`	Start provider-backed credential registration.
`POST`	`/admin/profile/webauthn/register/finish`	Complete credential registration.
`POST`	`/admin/profile/webauthn/authenticate/begin`	Start provider-backed authentication.
`POST`	`/admin/profile/webauthn/authenticate/finish`	Verify an authentication assertion.
`GET`	`/admin/profile/trusted-devices`	List the signed-in user's trusted devices.
`POST`	`/admin/profile/trusted-devices`	Issue one opaque trusted-device token after MFA.
`DELETE`	`/admin/profile/trusted-devices/{device_id}`	Revoke one trusted device.
`POST`	`/admin/profile/mfa/recovery-codes`	Rotate MFA recovery codes and revoke trusted devices.
`GET`	`/admin/cms/api/scheduler/jobs`	Inspect durable scheduled-publication jobs.
`POST`	`/admin/cms/api/scheduler/jobs/{job_id}/retry`	Requeue a failed scheduled-publication job.
`GET`	`/admin/cms/api/media`	List reusable Admin media for CMS fields.

All authenticated Admin mutations require the session cookie and X-CSRF-Token. Use redis_url for shared sessions, rate limits, and multi-worker coordination.

Authorization

from flaxon.admin import (
    AsyncAuthorizationProvider,
    CasbinAuthorizationProvider,
    DefaultAuthorizationProvider,
    PermissionCatalog,
    RedisPolicySynchronizer,
    default_group_definitions,
)

PermissionCatalog exposes readable definitions for model view, add, change, and delete actions plus CMS capabilities. DefaultAuthorizationProvider is dependency-free and supports legacy aliases during migration. Set strict_permissions=True on AdminDashboard to require exact capabilities. CasbinAuthorizationProvider is an optional adapter for an application-owned PyCasbin enforcer; Casbin is not a Flaxon runtime dependency.

Use default_group_definitions() to seed the named Administrator, Content Editor, Publisher, Media Manager, Warehouse Staff, Support Agent, and Read Only groups. The legacy staff and editor names remain available for migrations. A provider may implement async has_permission; Admin awaits it at every protected request boundary. RedisPolicySynchronizer publishes policy-change events and calls the enforcer's load_policy() in every worker.

Optional production dependencies

Install the feature groups explicitly:

pip install "flaxon[admin,policy,scheduler]"

The admin group adds nh3, Pillow, python-magic, Argon2, and WebAuthn; policy adds PyCasbin; scheduler adds APScheduler. python-magic also requires the platform's libmagic runtime. bandit and pip-audit are part of the development tools for CI security checks.

Microservice control plane

The control plane is enabled by default when AdminDashboard is created. The JSON API is rooted at /admin/api/control-plane/ and the browser pages use the same persistent records.

from flaxon.admin import (
    AdminControlPlane,
    RemoteModelAdapter,
    RemoteServiceClient,
    ServiceRegistry,
)

ServiceRegistry(self, store: Any | None=None, namespace: str='control_plane')

Atomic persistent catalog for services, instances and dependencies.

View implementation

Public methods and properties

`register`

def register(self, service: dict[str, Any] | ServiceRecord) -> dict[str, Any]

Perform the register operation for service registry.

`unregister`

def unregister(self, name: str) -> bool

Perform the unregister operation for service registry.

`get`

def get(self, name: str) -> dict[str, Any] | None

Retrieve the requested value using this object's configured behavior.

`list`

def list(self) -> list[dict[str, Any]]

Return the matching entries.

`set_instance`

def set_instance(self, service: str, instance: dict[str, Any]) -> dict[str, Any]

Set the instance.

`instances`

def instances(self, service: str | None=None) -> list[dict[str, Any]]

Perform the instances operation for service registry.

`set_dependencies`

def set_dependencies(self, service: str, dependencies: list[str]) -> list[dict[str, str]]

Set the dependencies.

`dependencies`

def dependencies(self, service: str | None=None) -> list[dict[str, str]]

Perform the dependencies operation for service registry.

RemoteServiceClient(self, base_url: str, *, token: str | None=None, timeout: float=5.0, retries: int=2)

Dependency-free JSON client for service-owned APIs.

It uses standard-library HTTP so the Admin does not require a second web framework or client package. Applications can subclass it for mTLS or replace it with their preferred async HTTP transport.

View implementation

Public methods and properties

`request`

async def request(self, method: str, path: str='/', *, body: Any=None, headers: dict[str, str] | None=None) -> Any

Perform the request operation for remote service client.

`get`

async def get(self, path: str='/') -> Any

Retrieve the requested value using this object's configured behavior.

`post`

async def post(self, path: str, body: Any=None) -> Any

`patch`

async def patch(self, path: str, body: Any=None) -> Any

`delete`

async def delete(self, path: str) -> Any

Delete the specified entry from the configured store.

RemoteModelAdapter(self, client: RemoteServiceClient, resource: str)

Model-shaped adapter for Admin registry entries backed by a service.

View implementation

Public methods and properties

`get_instances`

async def get_instances(self) -> list[dict[str, Any]]

Return the instances.

`get_instance`

async def get_instance(self, object_id: str) -> dict[str, Any] | None

Return the instance.

`create_instance`

async def create_instance(self, data: dict[str, Any]) -> Any

Create the instance.

`update_instance`

async def update_instance(self, object_id: str, data: dict[str, Any]) -> Any

Update the instance.

`delete_instance`

async def delete_instance(self, object_id: str) -> Any

Delete the instance.

AdminControlPlane(self, dashboard: Any)

Admin pages and APIs for service-owned microservice deployments.

View implementation

Public methods and properties

`page`

async def page(self, request: Request, section: str) -> Response

Perform the page operation for admin control plane.

`new_service_page`

async def new_service_page(self, request: Request) -> Response

Render the new service page for the current request.

`service_page`

async def service_page(self, request: Request, service_name: str) -> Response

Render the service page for the current request.

`access_page`

async def access_page(self, request: Request, username: str) -> Response

Render the access page for the current request.

`api`

async def api(self, request: Request, resource: str) -> Response

Handle a request to this subsystem's API.

Use this capability in a full-stack app

Flaxon serves Python APIs and Teloce interfaces in one project. Keep validation, authorization and privileged operations on the server; components call those endpoints and present their results. Follow the full-stack lessons and Teloce integration reference to connect this capability to pages, components and application modules.