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

# Auth

> better-auth plus the web pages and typed client. Pick it to add authentication; skip it and your project ships without auth.

The **Auth** plugin (`auth-starter`) is how a Ship project gets authentication. It's the bridge between your web app and the API: selecting it adds the better-auth backend, the sign-in / sign-up / password-reset pages, the authenticated app shell, and the typed oRPC client the rest of your UI builds on. Skip it and your project ships a clean landing page with nothing to sign into.

<Info>Requires **PostgreSQL** (and pulls in [Mailer](/docs/mailer) for verification/reset emails and Cloud Storage for avatar uploads).</Info>

## What it adds

**API**

* [better-auth](https://better-auth.com/) configured for email/password (with verification + reset) and Google OAuth.
* `users` / `accounts` / `sessions` / `verifications` schemas and the auth route handler.

**Web** (merged into `apps/web`)

* routes: `sign-in`, `sign-up`, `forgot-password`, `reset-password`, the `_authenticated` guard and settings.
* the oRPC client (`services/api-client.service.ts`) and the `useApiQuery` / `useApiMutation` / `useApiForm` / `useCurrentUser` hooks.

## Why auth is a plugin

In 3.0.0 the base `apps/web` is just a landing page with **no dependency on the API**. Auth — and the oRPC client that talks to the API — lives in this plugin so that:

* **web-only** projects stay clean (no auth, no API client, no backend coupling),
* **full-stack** projects opt in, and
* any plugin with authenticated routes ([Admin](/docs/plugins/admin), [AI Chat](/docs/plugins/ai-chat)) builds on the `_authenticated` shell and hooks it provides.

```mermaid theme={null}
flowchart LR
  base["apps/web (base)<br/>landing only"] -->|+ Auth plugin| full["sign-in/up · _authenticated · oRPC client"]
  full --> admin["Admin plugin"]
  full --> chat["AI Chat plugin"]
```

## Using it

The `_authenticated` guard redirects signed-out users to `/sign-in`; inside it, `useCurrentUser()` reads the session and the typed `apiClient` calls the API. See [Calling the API](/docs/web/calling-api) for the client and hooks.

<img src="https://mintcdn.com/ship/UByoaHTxaOwKkFqs/images/dashboards/web-signin.png?fit=max&auto=format&n=UByoaHTxaOwKkFqs&q=85&s=f62be78d868a985593bd17d8658c7393" alt="Sign in" width="2880" height="1920" data-path="images/dashboards/web-signin.png" />

## Grant admin

Auth ships a CLI to flip a user's admin flag:

```bash theme={null}
pnpm --filter api admin:set -- user@example.com
```

Pair it with the [Admin](/docs/plugins/admin) plugin to get a user-management dashboard.