Documentation · Getting started · Source code

Warning

This is an early-stage project with many moving parts and mostly missing documentation. The API is not yet stable and breaking changes are expected.

Roadmap

Our vision is to build a comprehensive, flexible authentication toolkit for Python that handles everything from low-level factor primitives to high-level OIDC server capabilities.

Short-term: Core Foundation

• Factor primitives — building blocks for authentication factors
  • Email OTP
  • HOTP
  • TOTP
  • Passwords
  • Security keys
  • Passkeys
  • Social Login
• MFA authentication management — multi-factor authentication workflows

Mid-term: Integration Layer

• Sessions management — robust session handling
• ORM and web frameworks wrappers — seamless integration with popular frameworks

Long-term: Full Platform

• OIDC server — complete OpenID Connect provider implementation
• Team management — multi-user and organizational features
• And more — expanding the ecosystem

Development

Setup environment

We use uv to manage the development environment and production build, and just to manage command shortcuts. Ensure they are installed on your system.

Run just install to install the development dependencies and pre-commit hooks.

Run unit tests

You can run all the tests with:

just test

By default, tests run against an in-memory SQLite database. To run tests against other DBMS, PostgreSQL and MySQL, you'll need a Docker installation. Then, run the tests with:

just test-db

Format the code

Execute the following command to apply linting and check typing:

just lint

Publishing a release

1. Commit the release entries under Unreleased in CHANGELOG.md. From a clean release branch with Git signing configured, run just version patch, just version minor, or just version major. The recipe updates the version, changelog, and lockfile and creates a signed commit.
2. Preview the release body with just release-notes <version>, then push the branch and merge the release PR into main.
3. With the GitHub CLI authenticated, run just release <PR number>. This signs and pushes a tag for the exact commit that landed, even if main has advanced. After the checks pass, CI publishes to PyPI and then publishes the GitHub release.

The PyPI Trusted Publisher must match build.yml and the GitHub release environment.

Serve the documentation

The documentation and landing page use Zensical. Start the local preview with:

just docs-serve

Open http://localhost:8000. The preview reloads when documentation changes. Edit pages in docs/ and configure the site in zensical.toml.

Build the static site into site/ with:

just docs-build

License

This project is licensed under the terms of the MIT license.