---
module: profile.display
title: Display
tab: Claude
order: 40
audience: dev
---

Terse agent reference for **Profile → Display** (items-per-page, date/time format, timezone).

## Ownership
- **Backend + data owner: `hiveops-auth`** (port 8082, DB `hiveiq_auth`).
- **Frontend: `hiveops-profile`** (`profile.bcos.cloud`) — view-only; no backend of its own.
- Do NOT look for a `hiveops-profile` controller/DB — there is none.

## Endpoints (via gateway; JWT bearer required)
| Method | Path | Notes |
|--------|------|-------|
| GET | `/auth/api/users/me/preferences` | Returns full `UserPreferences` blob |
| PUT | `/auth/api/users/me/preferences` | Merge-update; non-null fields only; returns saved blob |

- Controller: `UserProfileController` `@RequestMapping("/auth/api/users/me")`.
- Target user = JWT subject (`@AuthenticationPrincipal`). No user-id path param exists.

## Auth / roles
- Route falls under `.anyRequest().authenticated()` in `SecurityConfig`.
- **Any authenticated role** (CUSTOMER/ADMIN/MSP_ADMIN/BCOS_ADMIN) — edits **own** prefs only.
- NOT `hasAnyRole('MSP_ADMIN','BCOS_ADMIN')`. No admin cross-user path.

## Storage
| Item | Value |
|------|-------|
| DB | `hiveiq_auth` |
| Table | `users` |
| Column | `preferences` (JSONB, `NOT NULL DEFAULT '{}'`) |
| Migration | `V9__add_user_preferences.sql` |
| Entity | `User.preferences` → `UserPreferences` POJO, `@JdbcTypeCode(SqlTypes.JSON)` |

## Display fields (subset of the blob)
| Field | Default | Server validation |
|-------|---------|-------------------|
| `itemsPerPage` | 25 | `@Min(1) @Max(500)` |
| `dateFormat` | `MM/DD/YYYY` | none |
| `timeFormat` | `12-hour` | none (`12-hour`\|`24-hour`) |
| `timezone` | `America/New_York` | none |

## Kafka / topics
- **None.** No producer, no consumer, no record-store/executor path for this feature.

## Gotchas
- PUT is a **partial merge** — only non-null request fields overwrite; omitting a field leaves it unchanged (safe to send just the 4 Display fields).
- `dateFormat`/`timeFormat`/`timezone` have **no server-side allowlist** — any string is persisted. Bad values propagate to consumer SPAs.
- Prefs are **applied client-side by each SPA** (each app calls GET). "App X ignores format" = that app not reading prefs, not an auth bug.
- Postgres is on the database VM (10.10.10.188) — ProxyJump, not the services VM.
- CORS is enforced by hiveops-auth `CORS_ALLOWED_ORIGINS`; `https://profile.bcos.cloud` must be listed.
- New/pre-V9 users have `preferences = '{}'` → GET still returns entity defaults.

## Do NOT
- Do NOT create/expect endpoints or tables in `hiveops-profile`.
- Do NOT assume admin gating — these are self-service, per-user.
- Do NOT PUT `itemsPerPage` outside `1..500` (400).
- Do NOT expect a Kafka event or mirror table on Display changes.
- Do NOT try to set another user's prefs via API — no such route; use a direct `hiveiq_auth.users` SQL edit.
- Do NOT full-replace the blob; send only the fields you intend to change.
