Better Auth for Python

Authentication for Python, ported from better-auth. Ships with FastAPI, Litestar, Flask and Django integrations, plus a Python client.

This is better-auth-server, the server package (import name better_auth). Docs: better-auth-py.oumarbarry.dev

Your users, sessions and accounts live in your own database. There is no hosted service to depend on and no per-user pricing. The API surface is the one the TypeScript original has proven in production.

Full parity with better-auth (TypeScript) v1.6.29: same routes, JSON shapes and error codes, 35 social providers, 26 built-in plugins.

from better_auth import BetterAuth, EmailAndPassword
from better_auth.integrations.fastapi import BetterAuthFastAPI
from fastapi import Depends, FastAPI

auth = BetterAuth(
    secret="...",  # openssl rand -base64 32
    base_url="http://localhost:8000",
    email_and_password=EmailAndPassword(enabled=True),
)

app = FastAPI()
ba = BetterAuthFastAPI(auth)
app.include_router(ba.router)  # mounts /api/auth/*

@app.get("/me")
async def me(result: dict = Depends(ba.require_session)):
    return result["user"]

These twenty lines are a working auth server. Sign-up, sign-in, sessions, sign-out, password reset, email verification and social login are mounted under /api/auth, with the same routes, JSON shapes and error codes as better-auth.

Features

• Email and password: sign-up, sign-in, change/set/verify password, reset flow, email verification.
• Social sign-in (OAuth2/OIDC): 35 built-in providers (GitHub, Google, Discord, Apple, GitLab, Microsoft Entra ID, Slack, Spotify, Twitch, Zoom, ...), custom providers in a few lines. PKCE, single-use database-backed state, token refresh, JWKS/id-token verification, and account linking guarded by provider email verification.
• Sessions in your database: HMAC-signed cookies, sliding expiry (expires_in/update_age), rememberMe, list and revoke endpoints, bearer tokens for API clients, an optional signed cookie cache to skip the DB read on /get-session.
• Two adapters out of the box: in-memory for dev and tests, SQLAlchemy 2 async for SQLite, PostgreSQL and MySQL (SQLModel engines work as-is). A custom adapter implements nine async CRUD methods over dict rows.
• 26 built-in plugins covering two-factor auth, admin, organization (teams + dynamic access control), API keys, passkeys (WebAuthn), JWT, an OAuth 2.1 authorization-server (oauth-provider), SSO (OIDC), generic OAuth, device authorization, SIWE (Sign-In with Ethereum), magic link, email OTP, username, anonymous sessions, multi-session and more. Plugins add routes, extend the database schema, and hook before/after every request.
• Pluggable secondary storage (Redis-shaped protocol), configurable rate limiting with better-auth's per-path rules, trusted-proxy client-IP resolution, and secrets rotation via versioned SecretConfig.
• Secure defaults: scrypt password hashing, CSRF origin checks, open-redirect protection on every callbackURL, timing-equalized sign-in, XChaCha20-Poly1305 cross-runtime encryption for stored secrets.
• The core is framework-agnostic. The FastAPI layer is about 80 lines over plain request/response dataclasses, and the Litestar (BetterAuthLitestar), Flask (BetterAuthFlask) and Django (BetterAuthDjango) layers follow the same pattern, WSGI included.

Compatibility with better-auth (TypeScript)

The wire protocol and storage format follow the TypeScript implementation closely. A Python service can share a database with a TypeScript better-auth app:

Known divergences: reset-password tokens are stored in the database (email-verification tokens are stateless HS256 JWTs, matching the TypeScript library); bearer-token reading is built into the core session layer (a plugin over there, bearer here only adds the response-side set-auth-token header); SAML (part of the sso plugin), scim, stripe and the browser client/expo/electron/cli packages are out of scope (server-side parity only, see the changelog; to call a Better Auth server from Python there is better-auth-client).

Install

uv add better-auth-server[fastapi,sqlalchemy]
# or: pip install "better-auth-server[fastapi,sqlalchemy]"

Extras: fastapi (the FastAPI integration), litestar (the Litestar integration), flask (the Flask integration), django (the Django integration), sqlalchemy (the async SQLAlchemy adapter), passkey (WebAuthn via webauthn, for the passkey plugin), sso (DNS TXT lookups via dnspython, for the sso plugin's domain verification). Requires Python 3.10 to 3.14.

Quickstart

Run the included demo:

uv run uvicorn examples.fastapi_app:app --reload

# health
curl -s localhost:8000/api/auth/ok

# sign up (sets a session cookie)
curl -s -c /tmp/jar -X POST localhost:8000/api/auth/sign-up/email \
  -H 'content-type: application/json' \
  -d '{"name": "Ada", "email": "ada@example.com", "password": "s3cret-password"}'

# who am I?
curl -s -b /tmp/jar localhost:8000/api/auth/get-session
curl -s -b /tmp/jar localhost:8000/me

# sign out
curl -s -b /tmp/jar -c /tmp/jar -X POST localhost:8000/api/auth/sign-out

API clients can skip cookies entirely and send Authorization: Bearer <token> with the token returned by sign-in or sign-up.

Configuration

from better_auth import (
    BetterAuth, EmailAndPassword, EmailVerification, SessionOptions, RateLimit, GitHub, Google,
)

async def send_reset(user, url, token): ...       # plug your mailer
async def send_verification(user, url, token): ...

auth = BetterAuth(
    secret=os.environ["BETTER_AUTH_SECRET"],       # >= 32 chars, required
    base_url="https://example.com",                # cookies become Secure/__Secure- on https
    base_path="/api/auth",                         # default
    adapter=SQLAlchemyAdapter(engine),             # default: MemoryAdapter() (dev only!)
    email_and_password=EmailAndPassword(
        enabled=True,
        min_password_length=8,
        require_email_verification=False,
        auto_sign_in=True,
        send_reset_password=send_reset,
        revoke_sessions_on_password_reset=False,
    ),
    email_verification=EmailVerification(
        send_verification_email=send_verification,
        send_on_sign_up=False,
        auto_sign_in_after_verification=False,
    ),
    social_providers={
        "github": GitHub(client_id="...", client_secret="..."),
        "google": Google(client_id="...", client_secret="..."),
    },
    session=SessionOptions(expires_in=7 * 86400, update_age=86400),
    rate_limit=RateLimit(enabled=True),            # better-auth path rules built in
    trusted_origins=["https://app.example.com"],   # extra origins for CSRF + redirects
    plugins=[...],
    hooks={"before": ..., "after": ...},           # around every auth request
    database_hooks={"user": {"create": {"before": ..., "after": ...}}},
)

Database

Tables follow better-auth's core schema (user, session, account, verification).

from sqlalchemy.ext.asyncio import create_async_engine
from better_auth.adapters.sqlalchemy import SQLAlchemyAdapter

engine = create_async_engine("postgresql+asyncpg://...")  # or sqlite+aiosqlite, mysql+aiomysql
adapter = SQLAlchemyAdapter(engine)
auth = BetterAuth(secret=..., adapter=adapter, ...)
await adapter.create_tables()  # dev convenience; use Alembic in production

A custom adapter implements nine async methods over dict rows. See better_auth.adapters.base.BaseAdapter (create, find_one, find_many, update, update_many, delete, delete_many, count, transaction); atomic consume_one/increment_one are derived from transaction for free.

Social providers

35 providers are built in: GitHub, Google, Discord, Apple, Atlassian, AWS Cognito, Dropbox, Facebook, Figma, GitLab, Hugging Face, Kakao, Kick, LINE, Linear, LinkedIn, Microsoft Entra ID, Naver, Notion, Paybin, PayPal, Polar, Railway, Reddit, Roblox, Salesforce, Slack, Spotify, TikTok, Twitch, Twitter/X, Vercel, VK, WeChat and Zoom (see better_auth.oauth.PROVIDER_REGISTRY for the full name-to-class map). Configure by instance or by name:

from better_auth import GitHub

social_providers = {
    "github": GitHub(client_id=..., client_secret=...),
    # or name-keyed, resolved against PROVIDER_REGISTRY:
    "gitlab": {"client_id": ..., "client_secret": ...},
}

POST /api/auth/sign-in/social {"provider": "github", "callbackURL": "/dashboard"} returns {"url": ..., "redirect": true}. Send the browser to that URL; the callback sets the session cookie and redirects to callbackURL. A custom provider is one dataclass:

from better_auth import OAuthProvider

okta = OAuthProvider(
    client_id=..., client_secret=..., provider_id="okta",
    authorization_endpoint="https://your-org.okta.com/oauth2/v1/authorize",
    token_endpoint="https://your-org.okta.com/oauth2/v1/token",
    userinfo_endpoint="https://your-org.okta.com/oauth2/v1/userinfo",  # OIDC userinfo shape
    scopes=["openid", "email", "profile"], use_pkce=True,
)

Override fetch_user() for providers whose user payload is not OIDC-shaped (see the GitHub and Discord sources).

Plugins

26 plugins ship with the package under better_auth.plugins_ext (two-factor, admin, organization, api-key, passkey, jwt, oauth-provider, sso, generic-oauth, device-authorization, siwe, magic-link, and more; see plugins_ext.__all__ for the full list). Pass instances via plugins=[...] on BetterAuth. Writing your own is a Plugin subclass:

from better_auth import AuthResponse, Plugin

class ApiKeys(Plugin):
    id = "api-keys"
    schema = {"apikey": {...}}                      # extra tables, migrated like core ones

    def routes(self):
        return [("POST", "/api-keys/create", self.create)]

    async def create(self, ctx):
        result = await ctx.require_session()
        ...
        return {"key": "..."}

    async def before(self, ctx):                    # runs before every endpoint
        return None                                 # or AuthResponse(...) to short-circuit

Security notes

• Non-GET requests are origin-checked (CSRF) against base_url and trusted_origins.
• Every callbackURL and redirectTo is validated against trusted origins, which blocks open redirects.
• Sign-in runs a dummy scrypt when the user does not exist, so unknown email and wrong password take the same time and return the same 401.
• Rate limiting defaults to in-memory, per process (RateLimit(storage="memory")); "database" and "secondary-storage" back it with the shared adapter or a KV store for multi-worker deployments. ip_address=IPAddressOptions(...) controls how the client IP is resolved from proxy headers (trusted-proxy chain, custom header list).
• MemoryAdapter is the default so quickstarts work. Switch to a real adapter for anything persistent.

Roadmap

The parity campaign against the TypeScript library is complete; the changelog tracks each catch-up against upstream releases. Still open: CLI schema migrations. Deliberately out of scope: open-api, telemetry/logger config groups, SAML, scim, stripe, and the TypeScript client/expo/electron/cli packages (server-side parity only).

Development

uv sync --all-extras
uv run pre-commit install
uv run pytest            # e2e over ASGI, both adapters, mocked OAuth
uv run ruff check .
uv run ty check

See CONTRIBUTING.md for guidelines. Commits follow Conventional Commits.

For AI agents

npx skills add oumarbarry/better-auth-py lists the skills in this repository; pick better-auth-py to install it for Claude Code and compatible harnesses. It covers setup, plugins, providers and TS-to-Python migration, and every snippet in it has been executed and verified. The documentation site serves llms.txt at /llms.txt (index) and /llms-full.txt (all pages, one file). Agents contributing to this repo are governed by AGENTS.md; the details live on the AI agents docs page.

License

MIT. Inspired by and API-compatible with better-auth, also MIT.