Skip to content

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.

SendGrid

SendGrid provides email delivery with straightforward API integration.

Setup

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

Configuration

Add these variables to your backend/.env file:

# Email provider
FS_EMAIL_PROVIDER="sendgrid"

# SendGrid configuration
FS_SENDGRID_API_KEY="SG.your-sendgrid-api-key-here"
FS_SENDGRID_SENDER_ADDRESS="noreply@yourdomain.com"
FS_SENDGRID_SENDER_NAME="Your App Name"

Testing Email Setup

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

Azure Email Service

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

# Email provider
FS_EMAIL_PROVIDER="azure"

# Azure Email configuration
FS_AZURE_EMAIL_CONNECTION_STRING="endpoint=https://..."
FS_AZURE_EMAIL_SENDER_ADDRESS="noreply@yourdomain.com"

Development Mode (Stub)

For local development without actual email sending:

FS_EMAIL_PROVIDER="stub"

This logs emails to console instead of sending them.

Payment Processing (Stripe)

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

Setup

  1. Create Stripe Account: Sign up at stripe.com
  2. Get API Keys: Find them in Stripe Dashboard → Developers → API keys
  3. Set Up Webhooks: Configure webhook endpoint for payment events

Configuration

# Stripe API keys
FS_STRIPE_API_KEY="sk_test_your-stripe-secret-key"
FS_STRIPE_WEBHOOK_SECRET="whsec_your-webhook-signing-secret"

# Stripe portal return URL (where users return after managing billing)
FS_STRIPE_PORTAL_RETURN_URL="/billing"

Webhook Setup

  1. In Stripe Dashboard: Go to Developers → Webhooks
  2. Add Endpoint: https://yourdomain.com/webhooks/stripe
  3. Select Events:
  4. customer.subscription.created
  5. customer.subscription.updated
  6. customer.subscription.deleted
  7. invoice.payment_succeeded

  8. invoice.payment_failed

  9. Copy Signing Secret: Add to FS_STRIPE_WEBHOOK_SECRET

Stripe Integration Features

The Stripe integration handles subscription plans, plan upgrades and downgrades, recurring payments, and customer portal access. Payment processing includes payment collection, payment method management, invoice generation, and failed payment handling. Customer management automatically creates customer records, collects billing addresses, and tracks payment history.

Testing Payments

Use Stripe's test card numbers:

# Test successful payment
4242 4242 4242 4242

# Test declined payment  
4000 0000 0000 0002

# Test 3D Secure
4000 0025 0000 3155

OAuth Authentication

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

Google OAuth

Setup

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

Configuration

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

Frontend Integration

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

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

Adding More OAuth Providers

To add GitHub, Microsoft, etc.:

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

Additional Configuration

OpenAI (Optional)

For AI-powered features:

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

Background Tasks

For scheduled tasks and session cleanup:

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

# Session cleanup settings
FS_CRON_SESSION_RETENTION_DAYS=7

Environment-Specific Configuration

Development Environment

# Development settings
FS_ENVIRONMENT="dev"
FS_BASE_WEB_URL="http://localhost:5173"
FS_BASE_API_URL="http://localhost:8000"

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

Production Environment

# Production settings
FS_ENVIRONMENT="prod"
FS_BASE_WEB_URL="https://app.yourdomain.com"
FS_BASE_API_URL="https://api.yourdomain.com"

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

Security Configuration

JWT & Sessions

# JWT secret for session tokens (generate with: openssl rand -base64 32)
FS_JWT_SECRET_KEY="your-jwt-secret-key-here"

# Session configuration
FS_SESSION_COOKIE_NAME="session_id"
FS_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/reset \
  -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

  1. Check API Key: Verify SendGrid API key is correct
  2. Verify Sender: Ensure sender email is verified in SendGrid
  3. Check Logs: Look for email service errors in backend logs
  4. Test Connectivity: Ensure your server can reach SendGrid APIs

Stripe Webhooks Failing

  1. Verify Endpoint: Ensure webhook URL is accessible from internet
  2. Check Secret: Verify webhook signing secret matches
  3. Review Events: Check Stripe dashboard for webhook delivery attempts
  4. Test Locally: Use ngrok for local webhook testing

OAuth Issues

  1. Redirect URI: Ensure redirect URI matches exactly in OAuth provider
  2. Client Credentials: Verify client ID and secret are correct
  3. API Scope: Check if required OAuth scopes are enabled
  4. 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:

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