Authentication

Scira uses Better Auth for authentication, supporting multiple OAuth providers including GitHub, Google, and Twitter/X. This guide covers setting up authentication providers and managing user sessions.

Better Auth Integration

Better Auth is a modern authentication library that provides:

Multiple OAuth provider support
Session management
Rate limiting
Secure cookie handling
Database integration via Drizzle ORM

Authentication Configuration

The main authentication configuration is in lib/auth.ts:

import { betterAuth } from 'better-auth/minimal';
import { nextCookies } from 'better-auth/next-js';
import { drizzleAdapter } from 'better-auth/adapters/drizzle';

export const auth = betterAuth({
  rateLimit: {
    max: 100,
    window: 60,
  },
  experimental: { joins: true },
  database: drizzleAdapter(db, {
    provider: 'pg',
    schema: {
      user,
      session,
      verification,
      account,
      // ... other tables
    },
  }),
  socialProviders: {
    github: {
      clientId: serverEnv.GITHUB_CLIENT_ID,
      clientSecret: serverEnv.GITHUB_CLIENT_SECRET,
    },
    google: {
      clientId: serverEnv.GOOGLE_CLIENT_ID,
      clientSecret: serverEnv.GOOGLE_CLIENT_SECRET,
    },
    twitter: {
      clientId: serverEnv.TWITTER_CLIENT_ID,
      clientSecret: serverEnv.TWITTER_CLIENT_SECRET,
    },
  },
  trustedOrigins: [
    'http://localhost:3000',
    'https://scira.ai',
    'https://www.scira.ai'
  ],
  plugins: [lastLoginMethod(), nextCookies()],
});

Supported Providers

Scira supports three OAuth providers out of the box:

GitHub

Google

Twitter/X

OAuth Setup Instructions

GitHub OAuth

Create a GitHub OAuth App

Go to GitHub Developer Settings
Click “New OAuth App”
Fill in the application details:
- Application name: Scira (or your app name)
- Homepage URL: https://yourdomain.com
- Authorization callback URL: https://yourdomain.com/api/auth/callback/github
Click “Register application”

Get Client ID and Secret

After creating the app:

Copy the Client ID
Click “Generate a new client secret”
Copy the Client Secret (it won’t be shown again)

Configure environment variables

Add the credentials to your .env.local or .env file:

GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

Google OAuth

Create a Google Cloud Project

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Google+ API for your project

Create OAuth 2.0 Credentials

Navigate to APIs & Services → Credentials
Click “Create Credentials” → “OAuth client ID”
Configure the consent screen if prompted
Select “Web application” as the application type
Add authorized redirect URIs:
- https://yourdomain.com/api/auth/callback/google
- For local development: http://localhost:3000/api/auth/callback/google
Click “Create”

Get Client ID and Secret

After creating the credentials:

Copy the Client ID
Copy the Client Secret

Configure environment variables

Add the credentials to your .env.local or .env file:

GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_google_client_secret

Twitter/X OAuth

Create a Twitter App

Go to Twitter Developer Portal
Create a new project or select an existing one
Create a new app within the project

Configure OAuth 2.0

Navigate to your app’s settings
Enable OAuth 2.0
Set the Type of App to “Web App”
Add Callback URLs:
- https://yourdomain.com/api/auth/callback/twitter
- For local development: http://localhost:3000/api/auth/callback/twitter
Add Website URL: https://yourdomain.com

Get Client ID and Secret

From the app settings:

Copy the Client ID (OAuth 2.0)
Copy the Client Secret (OAuth 2.0)

Use OAuth 2.0 credentials, not OAuth 1.0a API keys.

Configure environment variables

Add the credentials to your .env.local or .env file:

TWITTER_CLIENT_ID=your_twitter_client_id
TWITTER_CLIENT_SECRET=your_twitter_client_secret

Session Management

Better Auth handles session management automatically with secure, HTTP-only cookies.

Session Schema

From lib/db/schema.ts:

export const session = pgTable(
  'session',
  {
    id: text('id').primaryKey(),
    expiresAt: timestamp('expires_at').notNull(),
    token: text('token').notNull().unique(),
    createdAt: timestamp('created_at').defaultNow().notNull(),
    updatedAt: timestamp('updated_at')
      .$onUpdate(() => new Date())
      .notNull(),
    ipAddress: text('ip_address'),
    userAgent: text('user_agent'),
    userId: text('user_id')
      .notNull()
      .references(() => user.id, { onDelete: 'cascade' }),
  },
  (table) => [index('session_userId_idx').on(table.userId)],
);

Session Features

Automatic expiration - Sessions expire based on expiresAt timestamp
Token-based - Unique token for each session
IP tracking - Stores IP address for security monitoring
User agent tracking - Records browser/device information
Cascade deletion - Sessions are deleted when user is deleted

User Schema

User accounts are stored in the user table:

export const user = pgTable('user', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  emailVerified: boolean('email_verified').default(false).notNull(),
  image: text('image'),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at')
    .defaultNow()
    .$onUpdate(() => new Date())
    .notNull(),
});

Account Schema

OAuth provider accounts are linked to users via the account table:

export const account = pgTable(
  'account',
  {
    id: text('id').primaryKey(),
    accountId: text('account_id').notNull(),
    providerId: text('provider_id').notNull(),
    userId: text('user_id')
      .notNull()
      .references(() => user.id, { onDelete: 'cascade' }),
    accessToken: text('access_token'),
    refreshToken: text('refresh_token'),
    idToken: text('id_token'),
    accessTokenExpiresAt: timestamp('access_token_expires_at'),
    refreshTokenExpiresAt: timestamp('refresh_token_expires_at'),
    scope: text('scope'),
    password: text('password'),
    createdAt: timestamp('created_at').defaultNow().notNull(),
    updatedAt: timestamp('updated_at')
      .$onUpdate(() => new Date())
      .notNull(),
  },
  (table) => [index('account_userId_idx').on(table.userId)],
);

Account Features

Multi-provider support - Users can link multiple OAuth providers
Token management - Stores access and refresh tokens
Token expiration - Tracks token expiration times
Scope tracking - Records OAuth scopes granted

Rate Limiting

Better Auth includes built-in rate limiting:

rateLimit: {
  max: 100,      // Maximum requests
  window: 60,    // Time window in seconds
}

This prevents brute force attacks by limiting authentication attempts.

Trusted Origins

Configure trusted origins for CORS and cookie security:

trustedOrigins: [
  'http://localhost:3000',
  'https://scira.ai',
  'https://www.scira.ai'
],
allowedOrigins: [
  'http://localhost:3000',
  'https://scira.ai',
  'https://www.scira.ai'
]

Important: Update these arrays to include your production domain when deploying.

Security Considerations

Use HTTPS

Always use HTTPS in production for secure cookie transmission

Secure secrets

Keep BETTER_AUTH_SECRET and OAuth secrets secure

Validate redirects

Only allow redirects to trusted origins

Monitor sessions

Track IP addresses and user agents for anomaly detection

Environment Variables

Ensure you have configured the authentication secret:

BETTER_AUTH_SECRET=your-generated-secret-here

Generate a secure secret:

openssl rand -base64 32

Never commit BETTER_AUTH_SECRET to version control or expose it publicly.

Testing Authentication

Local Development

Ensure OAuth apps have http://localhost:3000/api/auth/callback/{provider} in their callback URLs
Configure environment variables in .env.local
Start the development server:
pnpm dev
Navigate to http://localhost:3000 and test sign-in

Production

Update OAuth app callback URLs to your production domain
Configure production environment variables
Verify trustedOrigins includes your production domain
Test authentication flow in production

Troubleshooting

OAuth redirect URI mismatch

Ensure the callback URL in your OAuth app settings exactly matches:

https://yourdomain.com/api/auth/callback/{provider}

Common issues:

Missing trailing slash
HTTP vs HTTPS mismatch
Wrong subdomain (www vs non-www)

Session not persisting

Check:

BETTER_AUTH_SECRET is set
Cookies are enabled in browser
Domain is in trustedOrigins
HTTPS is enabled in production

Database connection errors

Verify:

DATABASE_URL is correct
Database migrations have been run
User, session, and account tables exist

Rate limit errors

If you’re hitting rate limits during testing:

Increase max in rate limit configuration
Clear Redis cache
Wait for the rate limit window to expire

Get Started

Features

Guides

Integrations

Authentication

Better Auth Integration

Authentication Configuration

Supported Providers

GitHub

Google

Twitter/X

OAuth Setup Instructions

GitHub OAuth

Google OAuth

Twitter/X OAuth

Session Management

Session Schema

Session Features

User Schema

Account Schema

Account Features

Rate Limiting

Trusted Origins

Security Considerations

Use HTTPS

Secure secrets

Validate redirects

Monitor sessions

Environment Variables

Testing Authentication

Local Development

Production

Troubleshooting

Next Steps

​Better Auth Integration

​Authentication Configuration

​Supported Providers

GitHub

Google

Twitter/X

​OAuth Setup Instructions

​GitHub OAuth

​Google OAuth

​Twitter/X OAuth

​Session Management

​Session Schema

​Session Features

​User Schema

​Account Schema

​Account Features

​Rate Limiting

​Trusted Origins

​Security Considerations

Use HTTPS

Secure secrets

Validate redirects

Monitor sessions

​Environment Variables

​Testing Authentication

​Local Development

​Production

​Troubleshooting

​Next Steps

Better Auth Integration

Authentication Configuration

Supported Providers

OAuth Setup Instructions

GitHub OAuth

Google OAuth

Twitter/X OAuth

Session Management

Session Schema

Session Features

User Schema

Account Schema

Account Features

Rate Limiting

Trusted Origins

Security Considerations

Environment Variables

Testing Authentication

Local Development

Production

Troubleshooting

Next Steps