Auth guards vary by endpoint — Create, Update, and Delete require an admin or benefit-provider OIDC token. Get and List accept any authenticated actor; app users (mobile JWT) see only active benefits, while admins see all.

Overview

A benefit is a specific offering — a free consultation or a health insurance policy — provided by a Benefit Provider. Benefits carry a benefit_type enum and a benefit_details JSONB block whose variant must match the type. Responses always include provider_name via a JOIN — callers never need a separate provider lookup.

Benefit Types

Type and details must be consistent at create time — a mismatch returns BE_503. (update_benefit does not re-validate this consistency.)
benefit_details is a serde-tagged enum. The discriminator key is benefit_type and its value is the SCREAMING_SNAKE_CASE variant name (CONSULTATION / INSURANCE_POLICY / HEALTH_CHECKUP) — the same value as the sibling benefit_type column. CONSULTATION and HEALTH_CHECKUP share one details shape (BasicBenefitDetails) but stay distinct variants — the tag is what tells them apart.

Insurance policy details

The INSURANCE_POLICY variant holds:
  • description — optional human-readable copy.
  • duration — externally-tagged single-key object: {"days": 90}, {"months": 12}, or {"years": 1}.
  • plans — a map keyed by free-form provider-defined plan_code (e.g. "1A", "2A", "2A1C"). Each PlanVariant carries daily_premium_amount, annual_premium_amount, coverage_amount (all amounts in minor units with a currency), optional grace_period_days, and nominee_required.
  • questionnaire — optional tree of Questions the policyholder answers at policy creation.

Visibility by Actor


Auth Guards by Endpoint


Endpoints

POST /benefits

Create a benefit. Provider must exist and be active. requirements is required; send [] for none.

GET /benefits

List benefits. App users see only ACTIVE ones. Filter by provider_id, benefit_type, status.

GET /benefits/available

Benefits the caller can avail right now. Unpaginated.

GET /benefits/{benefit_id}

Fetch a benefit by UUID. App users receive 404 for inactive benefits.

PATCH /benefits/{benefit_id}

Update name, description, benefit_details, or status.

DELETE /benefits/{benefit_id}

Soft-delete (status → INACTIVE).

Availability vs. the catalogue

GET /benefits is the catalogue: it answers what exists. GET /benefits/available answers what the calling user can act on. The two are adjacent and the word “available” does double duty — for an app user the catalogue is already forced to status = ACTIVE — so read them as exists vs can avail.
total on this endpoint is the count of benefits returned, not the size of the catalogue. The endpoint is unpaginated: the availability filter runs after the read, so a page would be ragged and its total wrong. The read is capped well above any realistic catalogue size, and the server logs a warning if that cap is ever reached.

How availability is decided

Every benefit carries five Superposition keys, overridable per benefit_type or benefit_id: For an app user they apply in that order against the user’s own benefit entities. An admin names the user in the x-user-id header and sees that user’s availability; without it the request is rejected with 400. Other callers with no user of their own are rejected with 400. Each entry wraps the benefit and adds the caller’s relationship to it:
The same rules gate creation — POST /users/{user_id}/insurance_policies (IP_1022), POST /users/{user_id}/consultations (CN_1617) and POST /benefit_entities (BEE_1706): a benefit the list would not offer as available is refused with 403. benefit.enabled = false blocks creation too.
An empty result is a 200 with data: [], never a 404 — “you can avail nothing right now” is an answer, not an error.

Request / Response Examples


Error Codes