Integrations¶

This guide covers configuration for email services, payment processing, and authentication providers.

Email Integration¶

The application supports multiple email providers for transactional emails including verification, password reset, and notifications.

Choosing a Provider¶

Set FR_EMAIL_PROVIDER in backend/.env to one of: resend, sendgrid, azure, or stub.

For the providers you don't use, clean up all three places:

backend/pyproject.toml — delete the two package lines you don't need, then run uv sync:

"azure-communication-email>=1.1.0",  # FR_EMAIL_PROVIDER=azure
"resend[async]>=2.0.0",              # FR_EMAIL_PROVIDER=resend
"sendgrid>=6.12.5",                  # FR_EMAIL_PROVIDER=sendgrid

cd backend && uv sync

backend/.env — remove the env vars for the unused providers.
backend/app/config/settings.py — remove the corresponding settings fields (e.g. resend_api_key, resend_sender_address, resend_sender_name).

Resend¶

Resend is a modern email API with a generous free tier — recommended for most new projects.

Setup¶

Create Resend Account: Sign up at resend.com
Get API Key: Create an API key at resend.com/api-keys
Verify Domain: Add and verify your sending domain at resend.com/domains

Configuration¶

FR_EMAIL_PROVIDER="resend"

FR_RESEND_API_KEY="re_your-resend-api-key-here"
FR_RESEND_SENDER_ADDRESS="noreply@yourdomain.com"
FR_RESEND_SENDER_NAME="Your App Name"

SendGrid¶

SendGrid provides email delivery with straightforward API integration.

Setup¶

Create SendGrid Account: Sign up at sendgrid.com
Get API Key: Create an API key in SendGrid dashboard
Verify Sender: Add and verify your sender email/domain

Configuration¶

FR_EMAIL_PROVIDER="sendgrid"

FR_SENDGRID_API_KEY="SG.your-sendgrid-api-key-here"
FR_SENDGRID_SENDER_ADDRESS="noreply@yourdomain.com"
FR_SENDGRID_SENDER_NAME="Your App Name"

Azure Email Service¶

For Azure-based deployments, you can use Azure Communication Services.

FR_EMAIL_PROVIDER="azure"

FR_AZURE_EMAIL_CONNECTION_STRING="endpoint=https://..."
FR_AZURE_EMAIL_SENDER_ADDRESS="noreply@yourdomain.com"

Development Mode (Stub)¶

For local development without actual email sending:

FR_EMAIL_PROVIDER="stub"

This logs emails to console instead of sending them.

Testing Email Setup¶

# Test email sending via API
curl -X POST http://localhost:8000/password/forgot \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

Payment Processing (Stripe)¶

The application integrates with Stripe for subscription billing, payment processing, and customer management.

For comprehensive documentation on Stripe integration including setup, local development, webhook configuration, testing, and troubleshooting, see the Stripe Integration Guide.

OAuth Authentication¶

The application supports social login via Google OAuth. The architecture can be extended for additional providers.

Google OAuth¶

Setup¶

Google Cloud Console: Go to console.cloud.google.com
Create Project: Or select existing project
Enable APIs: Enable Google+ API and Google OAuth2 API
Create Credentials: Create OAuth 2.0 Client ID
Configure Redirect: Add http://localhost:8000/auth/oauth/google/callback

Configuration¶

JWT Secret for OAuth State Validation

OAuth flows require a JWT secret for state parameter validation (CSRF protection). This is auto-generated by init.py. To generate manually:

python -c "import secrets; print(secrets.token_urlsafe(32))"
# or
openssl rand -base64 32

# Google OAuth
FR_GOOGLE_CLIENT_ID="your-google-client-id.apps.googleusercontent.com"
FR_GOOGLE_CLIENT_SECRET="GOCSPX-your-google-client-secret"

# JWT secret for OAuth state validation (CSRF protection)
FR_JWT_SECRET_KEY="your-jwt-secret-key-here"

Frontend Integration¶

Users can login with Google via the login page. The flow:

Frontend: Redirects to /auth/oauth/google/authorize-url
Backend: Returns Google authorization URL
User: Authenticates with Google
Google: Redirects to callback with authorization code
Backend: Exchanges code for user info and creates session
Frontend: User is logged in automatically

Adding More OAuth Providers¶

To add GitHub, Microsoft, etc.:

Extend OAuth Util: Add provider-specific functions in app/util/oauth_util.py
Add Routes: Create new OAuth routes in app/api/route/auth_route.py
Update Settings: Add provider credentials to app/config/settings.py

Additional Configuration¶

OpenAI (Optional)¶

For AI-powered features:

FR_OPENAI_API_KEY="sk-proj-your-openai-api-key"

Background Tasks¶

For scheduled tasks and session cleanup:

# Cron job authentication
FR_CRON_SECRET="your-secure-cron-secret"

# Session cleanup settings
FR_CRON_SESSION_RETENTION_DAYS=7

Environment-Specific Configuration¶

Development Environment¶

# Development settings
FR_ENVIRONMENT="dev"
FR_BASE_WEB_URL="http://localhost:5173"
FR_BASE_API_URL="http://localhost:8000"

# Relaxed CORS for development
FR_CORS_ORIGINS="http://localhost:5173,http://localhost:4173"

Production Environment¶

# Production settings
FR_ENVIRONMENT="prod"
FR_BASE_WEB_URL="https://app.yourdomain.com"
FR_BASE_API_URL="https://api.yourdomain.com"

# Strict CORS for production
FR_CORS_ORIGINS="https://app.yourdomain.com"

Security Configuration¶

Session Configuration¶

# Session configuration
FR_SESSION_COOKIE_NAME="session_id"
FR_SESSION_COOKIE_MAX_AGE=86400  # 24 hours

CORS Configuration¶

CORS origins are configured per environment in app/config/settings.py:

@property
def cors_origins(self) -> list[str]:
    return {
        "dev": ["http://localhost:5173", "http://localhost:4173"],
        "beta": ["https://app-beta.yourdomain.com"],
        "prod": ["https://app.yourdomain.com"],
    }.get(self.environment, [])

Testing Integrations¶

Email Testing¶

# Test password reset email
curl -X POST http://localhost:8000/password/forgot \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Stripe Testing¶

# Test creating a checkout session
curl -X POST http://localhost:8000/subscription/checkout \
  -H "Content-Type: application/json" \
  -H "Cookie: session_id=your-session-token" \
  -d '{"price_id": "price_test_123"}'

OAuth Testing¶

Visit http://localhost:8000/auth/oauth/google/authorize-url to get the Google authorization URL and test the OAuth flow.

Common Issues & Troubleshooting¶

Email Not Sending¶

Check API Key: Verify your provider API key is correct
Verify Sender: Ensure sender email is verified with your provider
Check Logs: Look for email service errors in backend logs
Test Connectivity: Ensure your server can reach the email API

Stripe Webhooks Failing¶

Verify Endpoint: Ensure webhook URL is accessible from internet
Check Secret: Verify webhook signing secret matches
Review Events: Check Stripe dashboard for webhook delivery attempts
Test Locally: Use stripe listen CLI for local webhook testing

OAuth Issues¶

Redirect URI: Ensure redirect URI matches exactly in OAuth provider
Client Credentials: Verify client ID and secret are correct
API Scope: Check if required OAuth scopes are enabled
HTTPS Required: Most providers require HTTPS in production

Production Checklist¶

Before deploying to production:

[ ] Email: Verify sender domain and set up SPF/DKIM records
[ ] Stripe: Switch to live API keys and test with real payments
[ ] OAuth: Update redirect URIs to production domains
[ ] CORS: Set strict CORS origins for production environment
[ ] Secrets: Use strong, unique secrets for JWT and webhooks
[ ] SSL/TLS: Enable HTTPS for all API endpoints
[ ] Monitoring: Set up error tracking and application monitoring

Next Steps¶

With integrations configured:

Architecture Overview - Learn about the system structure
Deployment - Deploy to production