Authentication - Usage guide¶

This guide shows you how to implement authentication in your FastEdgy application.

Configuration¶

Set authentication settings in your environment file (.env):

AUTH_SECRET_KEY=your-very-long-secret-key-here-at-least-32-chars
AUTH_ALGORITHM=HS256
AUTH_ACCESS_TOKEN_EXPIRE_MINUTES=15
AUTH_REFRESH_TOKEN_EXPIRE_DAYS=30

User registration¶

# User registration happens via the built-in endpoint
# POST /auth/register
{"name": "John Doe", "email": "john@example.com", "password": "secure_password"}

Or create users programmatically:

from fastedgy.depends.security import hash_password
from fastedgy.dependencies import Inject
from fastedgy.orm import Registry


async def create_user(name: str, email: str, password: str, registry: Registry = Inject(Registry)):
    User = registry.get_model("User")

    hashed_password = hash_password(password)
    user = User(name=name, email=email, password=hashed_password)
    await user.save()
    return user

# Login via built-in endpoint
# POST /auth/token
{
    "username": "john@example.com",  # Email as username
    "password": "secure_password",
}

# Returns:
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token_type": "bearer",
}

Protecting endpoints¶

from fastedgy.depends.security import get_current_user
from fastedgy.models.user import BaseUser
from fastapi import Depends


@app.get("/profile")
async def get_profile(current_user: BaseUser = Depends(get_current_user)):
    return {"id": current_user.id, "name": current_user.name, "email": current_user.email}


@app.post("/protected-action")
async def protected_action(data: dict, current_user: BaseUser = Depends(get_current_user)):
    # Only authenticated users can access this
    return {"message": f"Hello {current_user.name}", "data": data}

Token refresh¶

# Refresh access token via built-in endpoint
# POST /auth/refresh
{"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."}

# Returns new access token
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token_type": "bearer",
}

Using tokens in requests¶

Include the access token in your API requests:

# Authorization header
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

# Example with curl
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     http://localhost:8000/api/profile

Password reset¶

The built-in endpoints handle password reset flow:

Request reset: POST /auth/forgot-password
Validate token: POST /auth/forgot-password/validate
Reset password: POST /auth/reset-password

# 1. Request password reset
{"email": "john@example.com"}

# 2. User receives email with reset token
# 3. Reset password with token
{"token": "reset-token-from-email", "password": "new_secure_password"}

Custom user model¶

Extend the base user model:

from fastedgy.models.user import BaseUser
from fastedgy.orm import fields
from fastedgy.api_route_model import api_route_model


@api_route_model()
class User(BaseUser):
    phone = fields.CharField(max_length=20, null=True)
    is_verified = fields.BooleanField(default=False)
    created_at = fields.DateTimeField(auto_now_add=True)

    class Meta:
        tablename = "users"

Error handling¶

Authentication endpoints return standard HTTP errors:

400 Bad Request: Email already registered
401 Unauthorized: Invalid credentials
422 Unprocessable Entity: Invalid request data

try:
    # Your authentication logic
    pass
except HTTPException as e:
    if e.status_code == 401:
        # Handle invalid credentials
        pass

Back to Overview