# 01 — Auth & Session

← [Back to index](README.md) · Auth model, headers, and error format are in the
[README](README.md#3-authentication--multi-tenancy).

**Auth is email + password** (not OTP). All endpoints here are unauthenticated except
`POST /auth/logout` and `GET /me`.

---

## `POST /auth/register`
Creates a clinic (tenant) + owner (doctor).

**Request**
```json
{
  "clinicName": "عيادة الدكتور أحمد",
  "ownerName": "د. أحمد عبدالله",
  "email": "ahmed@example.com",
  "password": "secret123"
}
```
Validation: `clinicName` required · `ownerName` required · `email` required|email|unique ·
`password` required|min:6.

**Response `201` — `AuthSession`**
```json
{
  "token": "eyJhbGciOi...",
  "refreshToken": "def502...",
  "userId": "u_123",
  "tenantId": "t_123",
  "tenantSlug": "ahmed-clinic",
  "planCode": "trial",
  "role": "doctor"
}
```
- `refreshToken` nullable. `role` = `doctor` here.
- `planCode` ∈ [PlanCode](11-enums.md). New signups typically `trial`.

---

## `POST /auth/login`
**Request**
```json
{ "email": "ahmed@example.com", "password": "secret123" }
```
**Response `200` — `AuthSession`** (same shape). `role` is `doctor` or `receptionist`
depending on which account matched. Bad credentials → `401`.

> The receptionist account is the one created via [Team](03-team.md). It logs in here with
> the email + password the owner set.

---

## `POST /auth/request-password-reset`
**Request** `{ "email": "ahmed@example.com" }`
**Response `200`** — empty. Always `200` even if the email is unknown (avoid enumeration).

---

## `POST /auth/logout`
Auth required. Invalidate the token. **Response `200`** — empty.

---

## `GET /me`
Auth required. Returns the current user + tenant context (used to refresh role/plan).
```json
{
  "userId": "u_123",
  "tenantId": "t_123",
  "tenantSlug": "ahmed-clinic",
  "planCode": "pro",
  "role": "receptionist",
  "ownerName": "د. أحمد عبدالله",
  "name": "سارة (سكرتيرة)",
  "email": "sara@example.com"
}
```

---

## `AuthSession` fields (contract)

| Field | Type | Nullable | Notes |
|---|---|---|---|
| `token` | string | no | Bearer token. |
| `refreshToken` | string | yes | Reserved; app stores it if present. |
| `userId` | string | no | |
| `tenantId` | string | no | |
| `tenantSlug` | string | no | Sent back as `X-Tenant`. |
| `planCode` | string | no | [PlanCode](11-enums.md). |
| `role` | string | no | **Add this** — `doctor` \| `receptionist`. |

---

## Plans (no endpoint required yet)

The plan-selection screen uses a **client-side catalogue** (`PlanCatalog`), so **no
`GET /plans` endpoint is needed** for launch. If you want server-driven pricing later,
expose `GET /plans` returning an array of:

| Field | Type | Notes |
|---|---|---|
| `code` | string | [PlanCode](11-enums.md) |
| `name` | string | |
| `tagline` | string | |
| `priceMonthlyEgpPiastres` | int | piastres |
| `priceAnnualEgpPiastres` | int | piastres |
| `features` | string[] | bullet list |
| `isRecommended` | bool | |
| `hasTrial` | bool | |

(`BillingCycle` enum: `monthly` \| `annual`.)
