> For the complete documentation index, see [llms.txt](https://docs.kangaroodev.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangaroodev.net/product-docs/getting-started/authentication.md).

# Authentication

***

### Login (email + password)

1. User submits email and password on `/login.html`.
2. Backend checks credentials (e.g. bcrypt or your chosen hash) and loads the user from the database.
3. If valid, the server creates a **session object** (e.g. `{ id, role, ... }`) and sets a cookie `admin_session` with that payload (often JSON stringified and optionally signed/encoded).
4. Redirect: **admin** → `/admin.html` (or a default admin page); **non-admin** → `/client-dashboard.html`.

***

### Registration

* **Register** link on the login page sends email, username, password to `/api/auth/register`.
* User is created in the database with a default role (e.g. `client`). No auto-login is required by this doc; implement if desired.
* An admin can then change the user’s role and permissions in the panel.

***

### Discord OAuth (optional)

1. Configure a Discord Application in the Discord Developer Portal. Add a redirect URI: `https://your-domain/api/auth/callback` (must match `APP_BASE_URL`).
2. Set in env (or Admin Settings): **Discord Client ID**, **Client Secret**, **Redirect URI**.
3. User clicks “Login with Discord” on the login page → redirect to Discord → after approval, Discord redirects to `/api/auth/callback` with a code.
4. Backend exchanges the code for an access token, fetches Discord user, finds or creates a user in your DB (by `discordId`), creates a session, sets cookie, redirects as in normal login.

***

### Password reset

1. User requests reset (e.g. “Forgot password” on login page). Request goes to `/api/auth/request-password-reset` with email.
2. Backend finds the user, creates a **PasswordReset** record (token hash, expiry), and sends an email with a link: `/reset-password.html?token=...`. If SMTP is not configured, the link is printed in the server console (dev only).
3. User opens the link and submits a new password to `/api/auth/reset-password` with the token and new password.
4. Backend validates the token, updates the user’s password, invalidates the token, then redirects to login or auto-logs in (implementation-dependent).

**Admin-triggered reset:** Admins can request a password reset for another user (e.g. from a user management screen); same flow, but initiated by admin.

***

### Logout

* **GET** (or POST) `/api/auth/logout` clears the session cookie and redirects to `/login.html`.

***

### Protected routes

* HTML pages under `pages/` that are “protected” (e.g. `admin.html`, `commission.html`, `list.html`, `todo.html`, `hub.html`, `log.html`, `settings.html`, `client-dashboard.html`, `customer.html`, `commission-admin.html`) are served only after the middleware checks the session.
* If there is no valid session → redirect to `/login.html`.
* If there is a session, access to each page is then restricted by **role and permissions** (see Permissions & Roles). For example, `commission-admin.html` is only allowed for admin or users with Commissions permission; `commission.html` is allowed if the user has at least one assigned commission or Commissions permission.

***

### Session cookie

* Name: `admin_session`.
* Contains the minimal data needed to identify the user (e.g. `id`, `role`). The server loads full user (and permissions) from the database when needed.
* Ensure cookie is set with **SameSite** and **Secure** in production (HTTPS).