ServerAuth & Sessions

Overview

Authentication, session management, and token handling for the CRM platform.

Authentication in Selegic CRM is built on Better Auth and provides three authentication methods:

Session-based auth — Browser users authenticate via cookies
API key auth — Machine-to-machine requests using x-api-key header
Extension tokens — Short-lived JWTs for iframe-based extensions

The auth system is provided by @repo/crm-auth and surfaced to the server via middleware.

Core Components

Component	Location	Purpose
`auth`	`packages/crm-auth/src/index.ts`	Better Auth instance with plugins
`sessionMiddleware`	`crm/server/lib/middleware/session.ts`	Resolves session from browser cookies
`tenantMiddleware`	`crm/server/lib/middleware/tenant.ts`	Resolves org from API key or header
`requireAuth`	`crm/server/lib/middleware/auth.ts`	Route guard for protected endpoints

Architecture — Session lifecycle, token flows, route guards
Token Handling — API keys, session cookies, extension tokens
Runbook — Troubleshooting authentication issues

Key Features

Session Management

Cookie-based sessions with configurable cache (5-minute TTL)
Automatic organization assignment on session creation
Cross-subdomain cookies in production

Organization Support

Multi-tenant isolation via x-tenant-id header
API keys can specify target organization
Session users verified against organization membership

Plugins

The auth instance includes several Better Auth plugins:

organization — Multi-tenant organization support
admin — Admin role capabilities
apiKey — API key authentication
oneTap — Google One Tap login

Runbook

Troubleshooting common middleware and request-context issues.

Architecture

How sessions, API keys, and tenant resolution work in the CRM server.

On this page

Core Components Quick Navigation Key Features Session Management Organization Support Plugins