Implementation:Helicone Helicone Auth Config
| Knowledge Sources | |
|---|---|
| Domains | Authentication, Email Verification |
| Last Updated | 2026-02-14 06:32 GMT |
Overview
Server-side Better Auth configuration that initializes authentication with PostgreSQL, email verification via nodemailer, and custom session enrichment.
Description
This module configures the betterAuth instance used by the Helicone web application for server-side authentication. It establishes several key capabilities:
Database Connection: Creates a PostgreSQL connection pool using the DATABASE_URL environment variable.
Email/Password Authentication: Enables email and password sign-up with autoSignIn disabled, requiring users to verify their email first.
Email Verification: Configures nodemailer to send branded HTML verification emails. The SMTP transport adapts between environments:
- Development: Connects to MailHog (localhost:1025) with no authentication and relaxed TLS
- Production: Uses configured SMTP host, port, and credentials with proper TLS
The verification email includes Helicone branding, a "Start Building" CTA button, and tips about custom properties, caching, and prompt templates.
Trusted Origins: Restricts auth operations to the configured NEXT_PUBLIC_APP_URL or http://localhost:3008 as fallback.
Custom Session Plugin: Uses the customSession plugin to enrich session data by fetching the internal authUserId from the database via getUser, attaching it to the user object for downstream use.
Usage
This configuration is imported by the Next.js API routes that handle authentication endpoints. It should not be imported directly by client-side code.
Code Reference
Source Location
- Repository: Helicone
- File: web/lib/auth.ts
Signature
export const auth: BetterAuthInstance;
Import
import { auth } from "@/lib/auth";
I/O Contract
Environment Variables
| Variable | Required | Description |
|---|---|---|
| DATABASE_URL | Yes | PostgreSQL connection string for the auth database |
| SMTP_HOST | No | SMTP server hostname (defaults to "localhost") |
| SMTP_PORT | No | SMTP server port (defaults to 1025 for MailHog) |
| SMTP_SECURE | No | Whether to use TLS ("true" for port 465) |
| SMTP_USER | No | SMTP authentication username (skipped for MailHog) |
| SMTP_PASS | No | SMTP authentication password (skipped for MailHog) |
| NEXT_PUBLIC_APP_URL | No | Application base URL for email links and trusted origins |
| NODE_ENV | No | When "development", disables SMTP auth and logs verification URLs |
Session Enrichment
| Field | Type | Source | Description |
|---|---|---|---|
| user.authUserId | string |
Database lookup via getUser(user.id) |
Internal Helicone user ID attached to every session |
Authentication Features
| Feature | Configuration |
|---|---|
| Email/Password | Enabled with autoSignIn: false
|
| Email Verification | Sent on sign-up with branded HTML template |
| Trusted Origins | NEXT_PUBLIC_APP_URL or http://localhost:3008
|
| Custom Session | Attaches authUserId from database
|
Usage Examples
// In a Next.js API route handler
import { auth } from "@/lib/auth";
export default async function handler(req, res) {
const session = await auth.api.getSession({
headers: req.headers,
});
if (!session) {
return res.status(401).json({ error: "Unauthorized" });
}
// session.user.authUserId is available from custom session plugin
const userId = session.user.authUserId;
}