supertokens-python

supertokens-python is the Python client library for SuperTokens, an open-source user authentication platform. It runs inside your Python API process and handles the protocol between your app and the SuperTokens Core service, exposing session management, email/password login, passwordless login, social/enterprise SSO, multi-factor auth, and OAuth2 as independently configurable “recipes.”

Each recipe follows the same override-friendly pattern: a RecipeInterface for backend logic and an APIInterface for HTTP endpoints, both of which can be customized without forking the SDK. Framework adapters ship for FastAPI, Flask, and Django (including Django REST Framework), and every recipe exposes both async and generated sync function wrappers so it fits sync and async codebases alike.

It is aimed at teams that want an Auth0/Firebase-Auth-style feature set (sessions, social login, MFA, multi-tenancy) while self-hosting the auth layer and owning their user data.

What You Get

• Ready-made recipes for session management, email/password, passwordless, thirdparty (social/SSO) login, MFA/TOTP, OAuth2, WebAuthn, SAML, multi-tenancy, and user roles
• First-class middleware and request/response adapters for FastAPI, Flask, Django, and Django REST Framework
• Async-first APIs with generated sync wrappers, so the same SDK works in both async and traditional sync Python backends
• Override points (RecipeInterface, APIInterface) on every recipe to customize backend logic or HTTP responses without patching the SDK
• A Querier abstraction that centralizes all HTTP communication with SuperTokens Core, so recipes never talk HTTP directly
• Runnable examples for FastAPI, Flask, and Django under examples/, plus Docker Compose configs for local Core + OAuth2 test setups

Common Use Cases

• Adding session and login endpoints to a new FastAPI, Flask, or Django backend
• Self-hosting an open-source alternative to Auth0, Firebase Auth, or Clerk to keep full control of user data
• Layering MFA/TOTP onto an existing Django or DRF app without rewriting the current auth flow
• Giving a multi-tenant B2B SaaS product per-tenant login providers and user pools via the multitenancy recipe
• Adding social/enterprise SSO login (Google, GitHub, SAML, custom OAuth2/OIDC providers) to a Python API

Under The Hood

Architecture Every auth feature is a self-contained “recipe” under supertokens_python/recipe/<name>/, each following the same internal layout: recipe.py (a singleton RecipeModule subclass that’s the initialization entry point), interfaces.py (RecipeInterface and APIInterface, the two override surfaces), recipe_implementation.py (the default implementation, which calls SuperTokens Core through Querier), an api/ directory of HTTP handlers, and parallel asyncio//syncio/ directories exposing the same functions in async and sync form. The central supertokens.py module (roughly 970 lines) wires recipe initialization, plugins, and URL normalization together, while querier.py (roughly 550 lines) is the single chokepoint for all HTTP calls to Core, meaning protocol changes on the Core side only ever touch one file. Framework adapters under framework/{fastapi,flask,django}/ sit on top of this core and translate each framework’s native request/response objects into the SDK’s BaseRequest/BaseResponse abstractions, keeping recipe logic framework-agnostic.

Tech Stack A pure Python package (Python 3.8-3.13) distributed via setuptools with optional extras (fastapi, flask, django, django2x, drf) that pull in each framework plus its CORS/session middleware. Core runtime dependencies include httpx for async HTTP calls to SuperTokens Core, Pydantic v2 for typed request/response models, PyJWT[crypto] and pycryptodome for session-token cryptography, phonenumbers/pyotp/twilio for passwordless and MFA delivery, and tldextract/asgiref for cookie-domain handling and sync/async bridging. Tooling is Ruff (lint, format, import sorting) and Pyright in strict type-checking mode, enforced through pre-commit hooks; integration tests run against Docker Compose services for SuperTokens Core and an OAuth2 test provider.

Code Quality The tests/ tree is extensive and organized per recipe and per framework — dedicated suites for email/password, email verification, JWT, multitenancy, OAuth2, passwordless, SAML, plugins, Django, FastAPI, Flask, plus end-to-end auth-react frontend-integration tests. A conftest.py fixture resets all recipe singleton state before and after every test, and pytest runs with asyncio_mode = auto so async tests need no special decorator. The repository’s own contributor guide codifies explicit style rules (snake_case/PascalCase conventions, Literal from typing_extensions, no bare X | Y unions, one status class per output status), and CI runs a matrixed backend-SDK test suite plus separate lint and documentation-check workflows on every change — evidence of a project maintained to a deliberate internal standard rather than ad hoc.

API Design Every recipe shares one initialization pattern — init(app_info=..., framework=..., recipe_list=[session.init(), emailpassword.init(), ...]) — so learning to configure one auth feature transfers directly to the next. Override points follow the same shape across all ~17 recipes (a dict of functions patched onto RecipeInterface/APIInterface), avoiding the need to learn a different customization mechanism per feature. Shipping both async and generated sync wrappers from a single codebase lets FastAPI and Flask/Django users share the same documentation and API surface. Framework adapters are intentionally thin, which keeps the cost of supporting a new framework low without touching recipe logic — and the project ships its own MCP server (mcp-server/) alongside the SDK, an unusual extra for a backend auth library.