> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browsary.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Session management, email verification, password resets, two-factor auth, and external identity endpoints.

## Session status

### GET `/api/auth`

* **Auth** – optional.
* **Response** – `{ status: "ok" | "email_not_verified" | "2fa_required", auth }` where `auth` echoes the JWT payload or `null`.

Use this endpoint to decide whether the user must verify email or pass 2FA before granting UI access.

## Account lifecycle

| Endpoint                  | Purpose              | Body                                                                  | Notes                                                                                           |
| ------------------------- | -------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `POST /api/auth/register` | Create an account.   | `{ firstName, lastName, email, password, confirmPassword, remember }` | Returns `{ status: "email_not_verified", token? }` and sets a cookie when `remember` is truthy. |
| `POST /api/auth/login`    | Issue a new session. | `{ email, password, remember }`                                       | Responses include `{ status, token? }`. Cookies inherit the `remember` flag.                    |
| `GET /api/auth/logout`    | Destroy the cookie.  | —                                                                     | Always returns `{ status: "logout" }`.                                                          |

## Email verification

| Endpoint                        | Auth           | Body             | Description                                                                         |
| ------------------------------- | -------------- | ---------------- | ----------------------------------------------------------------------------------- |
| `POST /api/auth/verify/request` | Signed-in user | `{ returnUrl? }` | Sends a verification email. `returnUrl` is optional and injected into the template. |
| `POST /api/auth/verify/submit`  | None           | `{ token }`      | Exchanges the emailed JWT for `{ status: "ok", token }` and refreshes the cookie.   |

## Password reset

| Endpoint                       | Auth | Body                                   | Description                                                      |
| ------------------------------ | ---- | -------------------------------------- | ---------------------------------------------------------------- |
| `POST /api/auth/reset/request` | None | `{ email, returnUrl? }`                | Issues a reset email if the account exists.                      |
| `POST /api/auth/reset/submit`  | None | `{ token, password, confirmPassword }` | Validates the token, updates the password, and logs the user in. |

## Two-factor authentication (TOTP)

All endpoints require an email-verified session.

* `POST /api/auth/2fa/enable/request` → `{ status: "2fa_setup", url, secret }`. `url` is a TOTP URI you can render as a QR code.
* `POST /api/auth/2fa/enable/submit` with `{ token }` confirms setup and issues a fresh cookie.
* `POST /api/auth/2fa/verify` with `{ token }` completes login when `status === "2fa_required"`.
* `POST /api/auth/2fa/reset` with `{ token }` rotates the 2FA secret and re-enters the `"2fa_setup"` state.

## External providers

| Endpoint                                     | Description                                                                                                                                                        |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET /api/auth/external/providers`           | Lists configured providers from `OPENID_PROVIDERS`.                                                                                                                |
| `GET /api/auth/external`                     | Signed-in view of linked accounts plus unsupported provider records.                                                                                               |
| `GET /api/auth/external/{provider}`          | Returns `{ status: "ok", account }` for a specific provider.                                                                                                       |
| `DELETE /api/auth/external/{provider}`       | Unlinks the provider for the current user.                                                                                                                         |
| `GET /api/auth/external/{provider}/init`     | Redirects to the provider’s authorization URL, persisting PKCE state in cookies.                                                                                   |
| `GET /api/auth/external/{provider}/redirect` | Handles the provider callback. Depending on context it links the account, logs a user in, or issues a short-lived token for `/api/auth/external/register/{token}`. |
| `POST /api/auth/external/register/{token}`   | Completes sign-up for users coming from the external redirect but without an existing Browsary account.                                                            |

All external flows set or clear the `openid_code` and `openid_state` cookies automatically. After a successful redirect, the user is taken to `/dashboard` unless you specify a different `returnUrl` inside your email templates.