FastAPI-React Authentication Package

A robust, type-safe authentication system for FastAPI backend and React/TypeScript frontend applications.

Features

- User registration with email verification
- JWT-based authentication
- OAuth2 password flow
- TypeScript types for all responses
- Error handling for all edge cases
- Email verification system
- Password reset functionality

Backend Setup

1. Install dependencies:
``bash
pip install fastapi[all] sqlalchemy passlib[bcrypt] python-jose[cryptography] python-multipart
`

2. Copy the backend module:
`python
from auth_system import setup_auth

In your FastAPI app


app = FastAPI()
auth_router = setup_auth(
database_url="your_database_url",
secret_key="your_secret_key",
email_config={
"smtp_host": "smtp.gmail.com",
"smtp_port": 587,
"smtp_user": "your_email",
"smtp_password": "your_app_password"
}
)
app.include_router(auth_router, prefix="/api/v1/auth")
`

Frontend Setup

1. Install dependencies:
`bash
npm install axios @types/axios
`

2. Import and use the auth client:
`typescript
import { createAuthClient } from 'auth-system'

const auth = createAuthClient({
baseUrl: 'http://localhost:8000/api/v1',
onTokenChange: (token) => {
// Handle token storage
localStorage.setItem('token', token)
}
})

// Use the auth client
await auth.register(email, password, fullName)
await auth.login(email, password)
await auth.verifyEmail(token, email)
`

Security Features

- Password hashing with bcrypt
- JWT token with configurable expiration
- CSRF protection
- Rate limiting
- Email verification required before login
- Secure password reset flow

Error Handling

All errors are properly typed and handled:
- Network errors
- Validation errors
- Authentication errors
- Server errors

Configuration Options

$3

- Database configuration
- JWT settings
- Email settings
- Password requirements
- Rate limiting options

$3

- Base URL
- Token storage
- Request timeouts
- Custom error handling

Environment Variables

The authentication package requires certain environment variables to be set. Create a .env file in your project root with the following variables:

$3


`env

Email Configuration (Gmail SMTP)

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_EMAIL=your-email@gmail.com
SMTP_PASSWORD=your-app-specific-password
SMTP_FROM_NAME=Your App Name Support
`

> Note: For Gmail, you'll need to use an App Password instead of your regular password. You can generate one in your Google Account settings under Security > 2-Step Verification > App passwords.

$3

`env
SECRET_KEY=your-super-secret-key-replace-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
`

$3

`env
FRONTEND_URL=http://localhost:3000
``

Best Practices

1. Always store sensitive information in environment variables
2. Use HTTPS in production
3. Implement rate limiting
4. Set appropriate token expiration times
5. Use secure password requirements
6. Implement proper logging

Common Issues and Solutions

1. CORS issues:
- Ensure CORS settings match your frontend URL
- Add all necessary CORS headers

2. Email verification:
- Test email configuration thoroughly
- Handle email sending failures gracefully

3. Token handling:
- Store tokens securely
- Implement proper token refresh
- Clear tokens on logout

4. Form data:
- Use proper content types
- Handle validation errors correctly

Testing

Includes comprehensive tests for:
- User registration
- Login/logout
- Email verification
- Password reset
- Error cases
- Token handling