Quick Start

Get a working AllSafe Fast authentication system running in under five minutes. This guide walks you through installation, configuration, and protecting your first route with email/password authentication.

Prerequisites

• Python 3.11 or later
• FastAPI project (or create a new one)
• For production: PostgreSQL and Redis (not needed for this quick start)

Step 1: Install AllSafe Fast

Install AllSafe Fast using pip:

Or with Poetry:

Step 2: Configure AllSafe Fast

AllSafe Fast can be configured via environment variables or directly through the AuthConfig class. For this quick start, we'll use the in-memory storage adapter (no database required):

Step 3: Create the Auth Instance

Create an Auth instance and attach it to your FastAPI application. The Auth class is the main entry point for AllSafe Fast:

from fastapi import FastAPI, Depends
from allsafe_fast import Auth, AuthConfig, UserPrincipal

# Create the FastAPI app
app = FastAPI(title="My App")

# Create the Auth instance
# AuthConfig reads from environment variables by default
# You can also pass overrides directly:
auth = Auth(AuthConfig(
    secret_key="dev-secret-key-change-in-production",
    env="development",
))

# Attach the auth router to your app
# This adds sign-in, sign-up, refresh, and other auth endpoints
app.include_router(auth.router)

Step 4: Protect Your First Route

Use the auth.user() dependency to protect routes. This ensures only authenticated users can access them:

# Public route — no authentication required
@app.get("/")
async def root():
    return {"message": "Welcome to My App"}

# Protected route — any authenticated user can access
@app.get("/api/me")
async def get_me(user: UserPrincipal = Depends(auth.user())):
    return {
        "id": str(user.id),
        "email": user.email,
        "email_verified": user.email_verified,
        "roles": list(user.roles),
        "permissions": list(user.permissions),
    }

# Admin-only route — requires the "admin" role
@app.get("/api/admin")
async def admin_only(user: UserPrincipal = Depends(auth.user(role="admin"))):
    return {"message": "Hello, admin!"}

# Permission-protected route — requires specific permission
@app.post("/api/reports/export")
async def export_report(
    user: UserPrincipal = Depends(auth.user(permission="reports:export"))
):
    return {"message": "Report exported"}

Complete Working Example

Here is the complete, runnable application. Save it as main.py:

# main.py
from fastapi import FastAPI, Depends
from allsafe_fast import Auth, AuthConfig, UserPrincipal

app = FastAPI(title="My App with AllSafe Fast")

# Create Auth instance with development configuration
auth = Auth(AuthConfig(
    secret_key="dev-secret-key-change-in-production",
    env="development",
))

# Include the auth router (adds /auth/* endpoints)
app.include_router(auth.router)

# --- Public Routes ---

@app.get("/")
async def root():
    return {"message": "Welcome! Visit /docs for API documentation."}

# --- Protected Routes ---

@app.get("/api/me")
async def get_me(user: UserPrincipal = Depends(auth.user())):
    return {
        "id": str(user.id),
        "email": user.email,
        "email_verified": user.email_verified,
        "roles": list(user.roles),
        "permissions": list(user.permissions),
    }

@app.get("/api/admin")
async def admin_panel(user: UserPrincipal = Depends(auth.user(role="admin"))):
    return {"message": "Welcome to the admin panel", "admin": user.email}

# --- Run the app ---
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Step 5: Run the Application

Start the development server:

Step 6: Test with curl

Test the authentication flow using curl. AllSafe Fast automatically provides sign-up and sign-in endpoints:

Sign Up a New User

Access a Protected Route

Try the Admin Route (Without Admin Role)

Sign In and Refresh

What's Next

Congratulations! You have a working authentication system. Here's where to go from here:

Environment Variables Reference

AllSafe Fast reads configuration from environment variables. Here are the key ones for this quick start: