Auth API Overview

The Auth API provides a unified authentication layer supporting multiple providers: BetterAuth, NextAuth, Clerk, and AuthKit. Switch between providers via the AUTH_PROVIDER environment variable without changing your application code.

Supported Providers

Configuration

Set your preferred provider in .env.local:

# Choose your auth provider
AUTH_PROVIDER=betterauth  # Options: betterauth, nextauth, clerk, authkit

# Provider-specific credentials
AUTH_SECRET=your-secret-key
AUTH_URL=http://localhost:3000

Base URL

https://api.yourdomain.com/api/auth

Authentication Methods

All providers support:

• Email/Password - Traditional credential-based auth
• OAuth - Google, GitHub, GitLab, and more
• Magic Links - Passwordless email authentication
• SSO/SAML - Enterprise single sign-on (AuthKit, Clerk)

Common Endpoints

Response Format

All responses follow a consistent structure across providers:

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_123",
      "email": "user@example.com",
      "name": "John Doe"
    },
    "session": {
      "token": "eyJhbGciOiJIUzI1NiIs...",
      "expiresAt": "2024-12-31T23:59:59Z"
    }
  },
  "message": "Authentication successful"
}

Error Handling

Standard HTTP status codes with provider-agnostic error messages:

Provider-Specific Notes

BetterAuth

• Self-hosted, no external dependencies
• Full database control via Drizzle schema
• Supports 2FA, passkeys, and session management

NextAuth

• Requires NEXTAUTH_URL and NEXTAUTH_SECRET
• OAuth providers configured via providers array
• JWT or database session strategies

Clerk

• Uses Clerk's hosted authentication
• Requires @clerk/nextjs package
• Automatic session management

AuthKit

• WorkOS-powered authentication
• Built-in enterprise SSO support
• Organization management included

Getting Started

1. Configure your chosen provider in .env.local
2. Set up database schema (for BetterAuth/NextAuth)
3. Implement sign-up and sign-in flows
4. Protect routes using the auth middleware

See individual endpoint documentation for detailed request/response examples.