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.

Authentication

Overview

Flaxon provides flexible authentication support through pluggable authentication backends.

Supported approaches include:

JWT authentication
Session-based authentication
API key authentication
OAuth2 providers
Custom authentication implementations

Flaxon does not force a single authentication strategy. Developers can choose the approach that best fits their application.

JWT Authentication

JWT (JSON Web Token) authentication is commonly used for APIs, mobile applications, and distributed systems.

Setup

from flaxon import Flaxon
from flaxon.security import (
    JWTBackend,
    AuthenticationMiddleware,
    login_required
)


app = Flaxon(
    "auth-app"
)


backend = JWTBackend(
    secret_key="your-secret-key"
)


app.add_middleware(
    AuthenticationMiddleware,
    backend=backend
)
````

---

# Login

Create a login endpoint that validates credentials and returns a token.

```python
from flaxon.security import User


@app.post("/login")
async def login(request):

    data = await request.json()


    user = await authenticate_user(
        data["username"],
        data["password"]
    )


    if not user:
        raise HTTPException(
            401,
            "Invalid credentials"
        )


    token = await backend.create_token(
        user
    )


    return {
        "token": token,
        "user": user.to_dict()
    }

Protecting Routes

Use login_required to protect authenticated endpoints.

@app.get("/profile")
@login_required
async def profile(request):

    user = getattr(
        request,
        "user"
    )


    return {
        "user": user.to_dict()
    }

Custom User Model

Applications can extend the default user model with custom fields and permissions.

from flaxon.security import User


class CustomUser(User):

    def __init__(
        self,
        id,
        username,
        email,
        roles=None
    ):

        super().__init__(
            id,
            username,
            email,
            roles
        )


        self.permissions = [
            "read",
            "write"
        ]


    def can_access_admin(self):

        return "admin" in self.roles

Session Authentication

Session authentication is useful for traditional web applications.

Example:

from flaxon.security import (
    SessionBackend,
    AuthenticationMiddleware
)


backend = SessionBackend()


app.add_middleware(
    AuthenticationMiddleware,
    backend=backend
)


@app.post("/login")
async def login(request):

    user = await authenticate_user(
        data
    )


    session_id = await backend.create_token(
        user
    )


    response = JSONResponse(
        {
            "success": True
        }
    )


    response.headers["set-cookie"] = (
        f"session_id={session_id}; "
        "HttpOnly; Path=/"
    )


    return response

API Key Authentication

API keys are useful for service-to-service communication and external integrations.

from flaxon.security import (
    APIKeyManager,
    api_key_required
)


manager = APIKeyManager()


key, hashed = manager.generate_key()


manager.register(
    key
)


app.state.api_key_manager = manager


@app.get("/protected")
@api_key_required
async def protected(request):

    return {
        "data": "secret"
    }

OAuth2 protocol helpers

Flaxon provides configurable OAuth2 protocol helpers for authorization URL creation and authorization-code/token refresh requests. They do not create login routes, validate callback state, provision users, or establish an application session automatically. Your application must implement those steps, or use a dedicated identity provider integration.

Example:

from flaxon.security import (
    OAuth2Provider,
    OAuth2Backend
)


provider = OAuth2Provider(

    client_id="your-client-id",

    client_secret="your-client-secret",

    authorization_endpoint=(
        "https://auth.example.com/authorize"
    ),

    token_endpoint=(
        "https://auth.example.com/token"
    ),

    redirect_uri=(
        "https://your-app.com/callback"
    )
)


backend = OAuth2Backend()


backend.register_provider(
    "example",
    provider
)


@app.get("/auth/login")
async def auth_login():

    url = backend.get_authorization_url(
        "example"
    )

    return RedirectResponse(url)


@app.get("/auth/callback")
async def auth_callback(request):

    code = request.query.get(
        "code"
    )


    user_data = await backend.authenticate(
        "example",
        code
    )


    return {
        "user": user_data
    }

Password Hashing

Passwords should never be stored as plain text.

Flaxon provides password hashing utilities.

from flaxon.security import (
    hash_password,
    verify_password
)


hashed = hash_password(
    "my-password"
)


is_valid = verify_password(
    "my-password",
    hashed
)


if needs_rehash(hashed):

    hashed = hash_password(
        "my-password"
    )

Complete Authentication Example

Example API with registration, login, and protected routes.

from flaxon import (
    Flaxon,
    HTTPException
)

from flaxon.security import (
    JWTBackend,
    AuthenticationMiddleware,
    login_required,
    User,
    hash_password,
    verify_password,
)


app = Flaxon(
    "auth-demo"
)


backend = JWTBackend(
    secret_key="your-secret-key"
)


app.add_middleware(
    AuthenticationMiddleware,
    backend=backend
)


# Example storage
# Use a database in production

users = {}


@app.post("/register")
async def register(request):

    data = await request.json()


    if data["username"] in users:

        raise HTTPException(
            400,
            "Username already exists"
        )


    user = User(

        id=len(users) + 1,

        username=data["username"],

        email=data["email"],

        roles=[
            "user"
        ]
    )


    users[data["username"]] = {

        "user": user,

        "password": hash_password(
            data["password"]
        )
    }


    return {

        "success": True,

        "user": user.to_dict()

    }



@app.post("/login")
async def login(request):

    data = await request.json()


    stored = users.get(
        data["username"]
    )


    if not stored:

        raise HTTPException(
            401,
            "Invalid credentials"
        )


    if not verify_password(
        data["password"],
        stored["password"]
    ):

        raise HTTPException(
            401,
            "Invalid credentials"
        )


    token = await backend.create_token(
        stored["user"]
    )


    return {
        "token": token
    }



@app.get("/profile")
@login_required
async def profile(request):

    user = getattr(
        request,
        "user"
    )


    return {
        "user": user.to_dict()
    }



@app.get("/admin")
@login_required
async def admin(request):

    user = getattr(
        request,
        "user"
    )


    if "admin" not in user.roles:

        raise HTTPException(
            403,
            "Admin access required"
        )


    return {
        "admin": True
    }

Security Recommendations

For production applications:

Store users in a database.
Use strong secret keys.
Enable HTTPS.
Rotate tokens when appropriate.
Use short-lived access tokens.
Protect sensitive routes with authorization checks.
Never store plain-text passwords.
Apply rate limiting to login endpoints.

Next Steps

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.

Upgrading authentication

JWT, password and session migration explains standard tokens, trusted key rotation, legacy password upgrades and secure cookie defaults. Legacy hexadecimal-signature JWTs require sign-in again.