Authentication - CharleOS

CharleOS uses Better Auth for authentication with separate systems for team members and clients. This page provides an overview of the auth architecture.

Two Auth Systems

CharleOS has two completely separate authentication systems:

Team Auth

Internal team members (developers, PMs, CSMs, managers)

Google OAuth only
Invite-only (no public signup)
Role-based access control
Session-based authentication

Client Portal Auth

Client employees accessing the client portal

Email/password authentication
Invitation workflow
Per-client access control
Separate database tables

These systems are completely isolated. A team member cannot log into the client portal with their team credentials, and vice versa.

Architecture Overview

Team Authentication Flow

User visits charle.agency
  ↓
"Sign in with Google" button
  ↓
Google OAuth consent screen
  ↓
Better Auth verifies @charle.co.uk email
  ↓
Session created → Dashboard

Client Portal Authentication Flow

Client visits clients.charle.agency
  ↓
Email + password sign-in
  ↓
Better Auth verifies credentials
  ↓
Session created → Client Portal

Database Tables

Team Auth Tables

Table	Purpose
`user`	Team member profiles
`session`	Active team sessions
`account`	OAuth provider connections
`user_preference`	UI preferences

Client Portal Auth Tables

Table	Purpose
`client_user`	Client portal users
`client_session`	Active client sessions
`client_account`	Client credentials
`client_verification`	Password reset tokens
`client_user_preference`	Client UI preferences

Access Control

Team Member Access Levels

CharleOS uses a two-tier access system:

Access Levels (System Permissions)

Level	Who	Permissions
Admin	Luke	Full system access, all features
Manager	Simon, Andre, Ben, Nic	Management features, reports, admin tools
Staff	Everyone else	Standard access based on work type

Work Types (Role-Based Features)

Work Type	Dashboard	Key Features
development	IC Dashboard	My Tasks, My Schedule, Time Tracking
design	IC Dashboard	My Tasks, My Schedule, Time Tracking
qa	IC Dashboard	My Tasks, My Schedule, Time Tracking
pm	PM Dashboard	Task scheduling, client blocks
csm	CSM Dashboard	Quotes, clients, help desk
sdr	Staff Dashboard	Limited access

Combined Logic:

accessLevel controls what management features you see
workType controls which dashboard and features you get
Example: A developer with manager access level sees the Manager Dashboard (not IC Dashboard)

Client Portal Access

Client users have simpler access control:

Role	Permissions
admin	Can manage other client users, approve quotes
member	Can view tasks, submit tickets, view quotes

Authentication Features

Team Authentication

Google OAuth

Only authentication method (no password)
Must use @charle.co.uk email
Profile picture synced from Google
Auto-uploaded to Cloudflare R2

Invite-Only System

No public signup page
Admin creates user accounts
Invitation email sent
User signs in with Google

Session Management

7-day session expiry
Automatically refreshed on activity
Stored in PostgreSQL
Tracks IP and user agent

Pending Approval Screen

New users start as “pending”
See waiting screen until admin assigns role
Prevents access to app features
Admin updates status to “active”

Client Portal Authentication

Email/Password

Password-based authentication
Passwords hashed with bcrypt
Password reset via email token
No Google OAuth

Invitation Workflow

CSM creates client user
Invitation email sent with token
Client sets password on first login
Token expires after 7 days

Per-Client Isolation

Users belong to one client
Can only see their client’s data
No cross-client access
Enforced at database level

Environment Variables

Team Auth

Variable	Description
`BETTER_AUTH_SECRET`	Secret for encrypting sessions (32+ chars)
`BETTER_AUTH_URL`	Base URL (`http://localhost:3000` local, `https://charle.agency` prod)
`NEXT_PUBLIC_BETTER_AUTH_URL`	Public-facing auth URL (client-side)
`GOOGLE_CLIENT_ID`	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret

Client Portal Auth

Uses the same Better Auth instance but with client-specific context:

Variable	Description
`NEXT_PUBLIC_CLIENT_PORTAL_URL`	Client portal URL (`http://clients.localhost:3000` local, `https://clients.charle.agency` prod)

Code Structure

Team Auth

lib/
├── auth.ts              # Better Auth config (team)
├── auth-client.ts       # Client-side auth hooks (team)
└── permissions.ts       # Permission checks

app/
├── (auth)/              # Auth pages (team login, pending)
├── (dashboard)/         # Protected team routes
└── api/auth/[...all]/   # Better Auth API handler

Client Portal Auth

lib/
├── client-auth.ts       # Better Auth config (client portal)
└── client-auth-client.ts # Client-side auth hooks (portal)

app/client-portal/
├── sign-in/             # Client portal login
├── invite/              # Client invitation flow
├── (authenticated)/     # Protected client routes
└── callback/            # Auth callback

Security Features

CSRF Protection

Better Auth includes built-in CSRF protection for all auth requests

Session Security

Sessions stored server-side in PostgreSQL
Tokens are random, not predictable
IP address and user agent tracked
Automatic session cleanup on expiry

Password Security (Client Portal)

Passwords hashed with bcrypt (cost factor 10)
Never stored in plain text
Password reset requires email verification
Tokens expire after 7 days

Domain Restrictions

Team auth: Only @charle.co.uk emails
Client portal: Per-client isolation
No cross-origin session sharing

Session Management

Team Sessions

// Check if user is authenticated
const { data: session } = await auth.api.getSession({
  headers: headers(),
});

if (!session) {
  redirect("/auth");
}

// Access user data
const user = session.user;
console.log(user.name, user.email, user.accessLevel);

Client Portal Sessions

// Check if client user is authenticated
const { data: session } = await clientAuth.api.getSession({
  headers: headers(),
});

if (!session) {
  redirect("/client-portal/sign-in");
}

// Access client user data
const clientUser = session.user;
console.log(clientUser.name, clientUser.clientId);

Common Auth Patterns

Protected Route (Server Component)

// app/(dashboard)/tasks/page.tsx
import { auth } from "@/lib/auth";
import { headers } from "next/headers";
import { redirect } from "next/navigation";

export default async function TasksPage() {
  const { data: session } = await auth.api.getSession({
    headers: headers(),
  });

  if (!session) {
    redirect("/auth");
  }

  // Check permissions
  if (!canViewTasks(session.user)) {
    redirect("/dashboard");
  }

  return <TasksList />;
}

Protected API Route

// app/api/tasks/route.ts
import { auth } from "@/lib/auth";
import { headers } from "next/headers";

export async function GET(req: Request) {
  const { data: session } = await auth.api.getSession({
    headers: headers(),
  });

  if (!session) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Fetch tasks...
}

Client-Side Auth Check

"use client";

import { useSession } from "@/lib/auth-client";

export function ProfileButton() {
  const { data: session, isPending } = useSession();

  if (isPending) return <Skeleton />;
  if (!session) return <SignInButton />;

  return <UserDropdown user={session.user} />;
}

Better Auth

Better Auth configuration details

Permissions

Role-based access control

Sessions

Session management and lifecycle

Environment Variables

Auth environment configuration

​Two Auth Systems

Team Auth

Client Portal Auth

​Architecture Overview

​Team Authentication Flow

​Client Portal Authentication Flow

​Database Tables

​Team Auth Tables

​Client Portal Auth Tables

​Access Control

​Team Member Access Levels

​Access Levels (System Permissions)

​Work Types (Role-Based Features)

​Client Portal Access

​Authentication Features

​Team Authentication

​Client Portal Authentication

​Environment Variables

​Team Auth

​Client Portal Auth

​Code Structure

​Team Auth

​Client Portal Auth

​Security Features

​Session Management

​Team Sessions

​Client Portal Sessions

​Common Auth Patterns

​Protected Route (Server Component)

​Protected API Route

​Client-Side Auth Check

​Related Documentation

Better Auth

Permissions

Sessions

Environment Variables

Two Auth Systems

Architecture Overview

Team Authentication Flow

Client Portal Authentication Flow

Database Tables

Team Auth Tables

Client Portal Auth Tables

Access Control

Team Member Access Levels

Access Levels (System Permissions)

Work Types (Role-Based Features)

Client Portal Access

Authentication Features

Team Authentication

Client Portal Authentication

Environment Variables

Team Auth

Client Portal Auth

Code Structure

Team Auth

Client Portal Auth

Security Features

Session Management

Team Sessions

Client Portal Sessions

Common Auth Patterns

Protected Route (Server Component)

Protected API Route

Client-Side Auth Check

Related Documentation