---
title: Auth
icon: key-new
description: Set up, configure, and run the Reloop auth microservice locally.
---
> For the complete documentation index, see [llms-docs.txt](/llms-docs.txt) or the site index [llms.txt](/llms.txt). Full docs corpus: [llms-full-docs.txt](/llms-full-docs.txt). Prefer markdown URLs (append `.md`) for agent consumption. Product skill: [skill.md](/skill.md).


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

<Tip>
Run [`bun setup`](/docs/setup) once from the monorepo root (Postgres + Redis via Docker). Env files come from `bun setup` / `bun env:setup`.
</Tip>


## Overview

| Property | Value |
| :--- | :--- |
| **Directory** | `apps/backend/auth` |
| **Port** | `8000` |
| **Local URL** | [https://local.reloop.sh/api/auth](https://local.reloop.sh/api/auth) |
| **Swagger UI** | [https://local.reloop.sh/api/auth/openapi](https://local.reloop.sh/api/auth/openapi) |
| **Stack** | ElysiaJS · Better Auth · PostgreSQL · Redis · NATS |


## Quick start

```bash
bun be:auth:dev
```

Or start every backend: `bun backend:dev` / `bun dev`.

<Warning>
Open the dashboard at [https://local.reloop.sh/dashboard](https://local.reloop.sh/dashboard), not `localhost:3001`. Session cookies are scoped to `local.reloop.sh`. Local OTP is `888888`.
</Warning>


## Environment

`apps/backend/auth/.env` — created/merged by `bun setup` / `bun env:setup` from `.env.dev`.

```bash
# 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=
```

| 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` | Public origin for OAuth / invites |
| `PORT` | **YES** | `8000` | Host port |
| `NATS_URL` | **YES** | `nats://localhost:4222` | Event bus |
| `DEFAULT_OTP` | No | `888888` | Dev OTP bypass |
| `DISABLE_SIGNUP` | No | `false` | Set `true` after creating an admin |


## Commands

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


## Architecture

| Layer | Detail |
| :--- | :--- |
| **Sessions** | Better Auth manages login, OAuth, and cookie sessions via Redis + Postgres |
| **Multi-tenancy** | Users belong to organizations through `member` (`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 |


## Next

<CardGroup cols={2}>
  <Card icon="rocket" title="Setup" href="/setup">
    One-command local bootstrap
  </Card>
  <Card icon="globe" title="Port reference" href="/setup/port">
    Gateway routes and ports
  </Card>
  <Card icon="home" title="Dashboard" href="/setup/frontend/dashboard">
    Product UI that consumes auth
  </Card>
  <Card icon="key-new" title="API Key" href="/setup/backend/api-key">
    Developer API keys
  </Card>
</CardGroup>