Auth | Reloop Docs

Complete Base Setup First

Ensure you've finished the Setup — before proceeding.

Service Overview

User signup, login, sessions, organizations, and workspace membership via Better Auth.

Property	Value
Directory	`apps/backend/auth`
Port	`8000`
Local URL	https://local.reloop.sh/api/auth
Swagger UI	https://local.reloop.sh/api/auth/openapi
Stack	`ElysiaJS` `Better Auth` `PostgreSQL` `Redis` `NATS`

Quick Start

Run from the monorepo root (requires Docker Postgres + Redis):

bun be:auth:dev

The service starts with hot reloading on port 8000.

Use the unified domain

Access the dashboard at https://local.reloop.sh/dashboard, not localhost:3001. Session cookies are scoped to local.reloop.sh.

Environment Configuration

Variables live in apps/backend/auth/.env. Running bun env:setup from the root auto-populates this file.

# Database & Cache
PG_URL=postgresql://reloop:reloop123@localhost:5432/reloop
REDIS_URL=redis://:reloop123@localhost:6379

# Better Auth
BETTER_AUTH_SECRET=tENkVU4GrhckuRw4Bcfh93EWgXOFcszn
BASE_URL="https://local.reloop.sh"
PORT=8000
NODE_ENV=development

# Event Bus
NATS_URL=nats://localhost:4222

# Local dev helpers
DEFAULT_OTP=888888
DISABLE_SIGNUP=false

# OAuth (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

Reference Table

Variable	Required	Default	Notes
`PG_URL`	YES	`postgresql://...`	Shared Postgres from Docker
`REDIS_URL`	YES	`redis://...`	Sessions and rate limits
`BETTER_AUTH_SECRET`	YES	—	Session encryption key
`BASE_URL`	YES	`https://local.reloop.sh`	Must match Caddy domain for cookies
`PORT`	YES	`8000`	Host port
`NATS_URL`	YES	`nats://localhost:4222`	Event bus
`DEFAULT_OTP`	NO	`888888`	Dev OTP bypass for first login
`DISABLE_SIGNUP`	NO	`false`	Set `true` after creating admin account

Development Commands

All commands run from the monorepo root.

Command	Description
`bun be:auth:dev`	Start dev server with hot reloading
`bun run --filter=auth build`	Compile production bundle
`bun run --filter=auth start`	Run compiled production build
`bun run --filter=auth check-types`	TypeScript type-check

Architecture

Layer	Detail
Sessions	Better Auth manages login, OAuth, and cookie-based sessions via Redis + Postgres.
Multi-tenancy	Users belong to organizations through the `member` table (`packages/db/src/schema/auth.ts`).
Events	Auth lifecycle events published to NATS under `auth.*`.
First login	Use OTP `888888` locally when `DEFAULT_OTP` is set.