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 abenefit_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
TheINSURANCE_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-definedplan_code(e.g."1A","2A","2A1C"). EachPlanVariantcarriesdaily_premium_amount,annual_premium_amount,coverage_amount(all amounts in minor units with acurrency), optionalgrace_period_days, andnominee_required.questionnaire— optional tree ofQuestions 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.
How availability is decided
Every benefit carries five Superposition keys, overridable perbenefit_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.200 with data: [], never a 404 — “you can avail nothing
right now” is an answer, not an error.