Benefit Module

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

`benefit_type`	`benefit_details` variant	Description
`CONSULTATION`	`CONSULTATION { description? }`	Teleconsultation or in-person doctor consultation
`INSURANCE_POLICY`	`INSURANCE_POLICY { description?, duration, plans, questionnaire? }`	Health, life, or accident insurance

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) — the same value as the sibling benefit_type column.

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

Endpoint	Guard	Notes
`POST /benefits`	`require_benefit_provider_strict(false, provider_id)`	Admin, or BP scoped to the payload’s provider; provider must be active
`GET /benefits`	none (any authenticated actor)	App users forced to active-only
`GET /benefits/{benefit_id}`	none (any authenticated actor)	App users get 404 for inactive
`PATCH /benefits/{benefit_id}`	`require_benefit_provider(false)` then strict on the resolved provider	Admin or benefit provider
`DELETE /benefits/{benefit_id}`	`require_benefit_provider(false)` then strict on the resolved provider	Sets `status → INACTIVE`

Endpoints

POST /benefits

Create a benefit. Provider must exist and be active.

GET /benefits

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

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).

Request / Response Examples

curl -X POST http://localhost:8080/benefits \
  -H 'Authorization: Bearer eyJhbGci...oidc-token...' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Free GP Consultation",
    "description": "One free general physician consultation per month",
    "benefit_type": "CONSULTATION",
    "provider_id": "018f4c2a-1b3e-7d8f-9a0b-2c3d4e5f6a7b",
    "benefit_details": {
      "benefit_type": "CONSULTATION",
      "description": "One free general physician consultation per month"
    }
  }'

{
  "id": "019a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
  "name": "Free GP Consultation",
  "description": "One free general physician consultation per month",
  "benefit_type": "CONSULTATION",
  "provider_id": "018f4c2a-1b3e-7d8f-9a0b-2c3d4e5f6a7b",
  "provider_name": "Narayana Health",
  "benefit_details": {
    "benefit_type": "CONSULTATION",
    "description": "One free general physician consultation per month"
  },
  "status": "ACTIVE",
  "created_at": "2026-04-12T10:05:00Z",
  "last_modified_at": "2026-04-12T10:05:00Z"
}

Error Codes

Code	HTTP	Description
`BE_500`	500	Internal server error
`BE_501`	404	Benefit not found
`BE_502`	409	Name already exists for this provider
`BE_503`	400	`benefit_type` / `benefit_details` variant mismatch
`BE_504`	404	Benefit provider not found or inactive
`BE_505`	400	Validation error (e.g. empty name)
`BE_506`	403	Caller is not authorized for this benefit’s provider

Overview

Architecture

Decisions

Modules

Overview

Benefit Types

Insurance policy details

Visibility by Actor

Auth Guards by Endpoint

Endpoints

POST /benefits

GET /benefits

GET /benefits/{benefit_id}

PATCH /benefits/{benefit_id}

DELETE /benefits/{benefit_id}

Request / Response Examples

Error Codes

​Overview

​Benefit Types

​Insurance policy details

​Visibility by Actor

​Auth Guards by Endpoint

​Endpoints

POST /benefits

GET /benefits

GET /benefits/{benefit_id}

PATCH /benefits/{benefit_id}

DELETE /benefits/{benefit_id}

​Request / Response Examples

​Error Codes

Overview

Benefit Types

Insurance policy details

Visibility by Actor

Auth Guards by Endpoint

Endpoints

Request / Response Examples

Error Codes