---
module: profile.notifications
title: Notifications
tab: Claude
order: 40
audience: dev
---

Terse agent reference. Act from this; do not infer beyond it.

## Ownership
- **Owning backend:** `hiveops-auth` (port 8082, NGINX `/api/auth/`, DB `hiveiq_auth`).
- **Frontend:** `hiveops-profile` → `frontend/src/components/Profile/NotificationSettings.svelte`; data via `frontend/src/lib/api.ts` `profileAPI`.
- **No** `hiveops-profile/backend`. **No** Kafka. **No** other service reads these flags.

## Endpoints (exact)
| Method | Path | Notes |
|---|---|---|
| GET | `/auth/api/users/me/preferences` | returns full `UserPreferences` JSON for caller |
| PUT | `/auth/api/users/me/preferences` | merge-update; null field = skip |
| GET | `/auth/api/users/me` | profile (not prefs) |
- Frontend baseURL = `window.__APP_CONFIG__.apiUrl` (NGINX gateway, default `http://localhost:8080`) → auth. Header: `Authorization: Bearer <localStorage 'token'>`.

## Auth / roles
- Security chain `/auth/api/**` → `.anyRequest().authenticated()`. **No** `@PreAuthorize`, **no** `hasAnyRole`.
- Row resolved by `@AuthenticationPrincipal` (JWT email). Strictly self-scoped. No admin cross-user path.

## Storage (exact)
- Table **`users`**, column **`preferences`** — `JSONB NOT NULL DEFAULT '{}'` (Flyway `V9__add_user_preferences.sql`).
- Hibernate: `@JdbcTypeCode(SqlTypes.JSON)` on `User.preferences` → POJO `UserPreferences` (not an entity).
- Notification JSON keys: `emailNotificationsEnabled`, `pushNotificationsEnabled`, `notifyOnCritical`, `notifyOnHigh`, `notifyOnAssignment`, `notifyOnStatusChange`, `notificationQuietStart`, `notificationQuietEnd`.
- Defaults: email/push/critical/high = `true`; assignment/statusChange = `false`; quiet start/end = `null`.

## Validation (PUT body → `UpdatePreferencesRequest`)
- `notificationQuietStart` / `notificationQuietEnd`: regex `^([01]\d|2[0-3]):[0-5]\d$` (24h `HH:MM`) or omit.
- (Non-notification, same doc) `sessionTimeoutMinutes` 5–480; `itemsPerPage` 1–500.

## Gotchas
- Merge is null-skip: PUT `notificationQuietStart: null` does **not** clear it — old value persists. To clear, edit DB: `UPDATE users SET preferences = preferences - 'notificationQuietStart' - 'notificationQuietEnd' WHERE email=...`.
- Flags are **stored only** — no consumer anywhere sends email/push, gates on severity, or enforces quiet hours. Changing toggles has no delivery effect currently.
- Empty/`{}` `preferences` column reads as all-defaults, not an error.
- DB is on VM `10.10.10.188` (ProxyJump via services VM), not the services host.
- CORS: `profile.bcos.cloud` must be in `hiveiq-auth` `CORS_ALLOWED_ORIGINS` (and mgmt).

## Do NOT
- Do NOT look for a `hiveops-profile` backend, a `preferences` table, or a Kafka topic — none exist.
- Do NOT claim admin/`MSP_ADMIN` can edit another user's notification prefs here.
- Do NOT tell a user these toggles change alert delivery — no pipeline consumes them yet.
- Do NOT send `null` to clear quiet hours and expect it to clear (server skips nulls).
- Do NOT route these calls to incident/messaging/devices — the Notifications tab uses only `hiveops-auth`.
