auth

Auth

SerpentStack ships with working local JWT authentication (register, login, token validation). This skill explains the auth architecture and how to swap providers.

How Auth Works (Built-in)

Architecture

POST /api/v1/auth/register  →  UserService.register()  →  bcrypt hash  →  DB  →  JWT
POST /api/v1/auth/login     →  UserService.authenticate()  →  verify hash  →  JWT
GET  /api/v1/auth/me        →  get_current_user dependency  →  decode JWT  →  UserResponse

Any protected route:
    @router.delete("/{id}")
    async def delete(user: UserInfo = Depends(get_current_user)):
        # user.user_id, user.email available here

Key Files

File	Role
backend/app/routes/auth.py	Auth routes + get_current_user dependency
backend/app/services/user.py	Registration, authentication, password hashing
backend/app/models/user.py	User SQLAlchemy model (email, hashed_password)
backend/app/schemas/user.py	Request/response schemas (register, login, token)
backend/app/middleware/auth.py	Optional global auth middleware (not enabled by default)

The UserInfo Contract

All protected routes receive a UserInfo object via dependency injection:

class UserInfo(BaseModel):
    user_id: str
    email: str | None = None
    name: str | None = None
    raw_claims: dict[str, Any] = {}

This is the interface between auth and the rest of the app. When swapping providers, keep this shape — every route that uses Depends(get_current_user) depends on it.

Protecting a Route

Add Depends(get_current_user) to any route that requires authentication:

from app.routes.auth import UserInfo, get_current_user

@router.post("")
async def create_thing(
    payload: ThingCreate,
    user: UserInfo = Depends(get_current_user),  # ← requires valid JWT
    db: AsyncSession = Depends(get_db),
    service: ThingService = Depends(get_thing_service),
) -> ThingResponse:
    thing = await service.create(payload, owner_id=user.user_id)
    await db.commit()
    return ThingResponse.model_validate(thing)