跳转至

Quickstart

apogee-auth is a CLI plugin, not a library. You do not import it — you install it into a generated project, and it scaffolds the RBAC entities, service, controller, middleware and migrations directly into your source tree, following the same Clean Architecture layout as the rest of the project.

That design is deliberate: the generated code is yours to read and change, and it has no runtime dependency back on apogee-auth.

Install the plugin

Bash
pip install apogee-auth

Once installed, the apogee binary picks it up through the apogee.plugins entry point, so the subcommands appear under the global CLI inside any generated project.

See what is available

Bash
apogee auth:list

Three module groups can be installed: core (users, roles, permissions, sessions, audit log), mfa (TOTP enrolment and verification) and api-keys.

Scaffold RBAC into your project

Bash
apogee auth:install --modules core --domain Auth --context main
Flag Default What it does
--modules / -m required Comma-separated: core, mfa, api-keys
--domain / -d Auth The business domain the entities land under
--context / -c main The db-context the migrations target
--package derived from the context Target Python package

Add MFA later without touching what is already generated:

Bash
apogee auth:install --modules mfa --context main

What lands in your project

The generator renders four templates alongside the domain entities and migrations, into the same layered structure apogee make:entity produces:

Generated file Layer Role
auth_service.py application Password hashing, session issue and revoke, permission checks
auth_controller.py presentation Framework-agnostic controller
auth_router.py presentation The HTTP routes
auth_middleware.py presentation Reads the session, populates the request principal

Run the migrations the install created:

Bash
apogee db-context-migrate --context main

Remove it again

auth:uninstall is reversible, and --dry-run lists what it would touch before anything is deleted.

Bash
apogee auth:uninstall --modules mfa --context main --dry-run
apogee auth:uninstall --modules mfa --context main

It can also roll the database back in the same step, by dispatching apogee db-context-migrate-down for the revisions the module added.

Runtime middleware

The generated middleware is deliberately thin. For the FastAPI and Starlette integration — AuthMiddleware, RBAC guards and the MFA helpers — see apogee-auth-runtime, which is an importable library.