Skip to main content

​
Overview

Featul uses better-auth for authentication with support for:
  • Email/password authentication with verification
  • Google OAuth
  • GitHub OAuth
  • Passkeys (WebAuthn)
  • Two-factor authentication (2FA)
  • Multi-session support

​
OAuth Providers

​
Google OAuth

To enable Google authentication:
  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Navigate to APIs & Services > Credentials
  4. Create OAuth 2.0 Client ID
  5. Add authorized redirect URIs:
    • https://yourdomain.com/api/auth/callback/google
    • http://localhost:3000/api/auth/callback/google (for development)
Make sure to enable the Google+ API in your Google Cloud project.
Add the credentials to your environment:
.env
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
Configuration in code: packages/auth/src/auth.ts:180-184

​
GitHub OAuth

To enable GitHub authentication:
  1. Go to GitHub Developer Settings
  2. Click “New OAuth App”
  3. Set the authorization callback URL:
    • https://yourdomain.com/api/auth/callback/github
    • http://localhost:3000/api/auth/callback/github (for development)
Add the credentials to your environment:
.env
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
Configuration in code: packages/auth/src/auth.ts:185-189

​
Email Verification

Email verification is required by default for email/password sign-ups: 
emailAndPassword: {
  enabled: true,
  autoSignIn: false,
  requireEmailVerification: true,
}

emailVerification: {
  sendOnSignUp: true,
  sendOnSignIn: true,
  autoSignInAfterVerification: true,
}
Configuration in code: packages/auth/src/auth.ts:167-177
Email verification requires configuring the email service. See the Email Configuration page.

​
Better Auth Secret

Generate a secure random secret for session encryption: 
BETTER_AUTH_SECRET=your_secure_random_secret_here
Use a cryptographically secure random string. Never commit this secret to version control.
Generate a secure secret using: 
openssl rand -base64 32

​
Cross-Subdomain Authentication

Featul supports multi-tenant subdomain routing with shared authentication:
.env
NEXT_PUBLIC_APP_URL=https://app.featul.com
AUTH_COOKIE_DOMAIN=featul.com
AUTH_TRUSTED_ORIGINS=https://featul.com,https://app.featul.com,https://*.featul.com
  • NEXT_PUBLIC_APP_URL: Your main application URL
  • AUTH_COOKIE_DOMAIN: Root domain for cross-subdomain cookies (e.g., .featul.com)
  • AUTH_TRUSTED_ORIGINS: Comma-separated list of trusted origins for CORS
Configuration in code: packages/auth/src/auth.ts:16-36,193-206
For localhost development, leave AUTH_COOKIE_DOMAIN empty or set it to localhost.

​
Passkeys (WebAuthn)

Configure passkey authentication for passwordless login:
.env
PASSKEY_RP_ID=localhost
PASSKEY_RP_NAME=Featul
PASSKEY_ORIGIN=http://localhost:3000
For production:
.env
PASSKEY_RP_ID=featul.com
PASSKEY_RP_NAME=Featul
PASSKEY_ORIGIN=https://app.featul.com
  • PASSKEY_RP_ID: Relying Party ID (your domain)
  • PASSKEY_RP_NAME: Display name for the passkey
  • PASSKEY_ORIGIN: Full origin URL of your application
Configuration in code: packages/auth/src/auth.ts:238-242

​
Rate Limiting

Authentication endpoints are rate-limited to prevent abuse. Rate limiting requires Redis:
.env
UPSTASH_REDIS_REST_URL=your_upstash_redis_url
UPSTASH_REDIS_REST_TOKEN=your_upstash_redis_token
Default rate limits:
  • Sign-in/Sign-up: 5 requests per 60 seconds
  • Password reset: 3 requests per 5 minutes
  • OTP verification: 5 requests per 60 seconds
Configuration in code: packages/auth/src/auth.ts:210-227
Get free Redis hosting at Upstash.

​
Session Configuration

Sessions are configured with:
  • Secure cookies in production
  • SameSite=None for cross-origin support
  • HTTP-only cookies
  • Multi-session support (multiple devices)
Configuration in code: packages/auth/src/auth.ts:192-206

Build docs developers (and LLMs) love

Get started for freeTalk to us