Auth guards vary by endpoint — Create, Update, Delete are admin-only. Get and List accept both JWT users (active benefits only) and the admin key (all benefits).
Overview
A benefit is a specific offering — a free consultation, an insurance policy, a diagnostic test — 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
benefit_type | benefit_details variant | Description |
|---|---|---|
consultation | Consultation { description } | Free or subsidised doctor consultation |
insurance_policy | InsurancePolicy { description } | Health or accident insurance |
BE-503.
Visibility by Actor
Auth Guards by Endpoint
| Endpoint | JWT user | Admin key | Notes |
|---|---|---|---|
POST /benefits | — | ✓ | Provider must be active |
GET /benefits | ✓ active only | ✓ all | |
GET /benefits/{id} | ✓ active only | ✓ all | |
PATCH /benefits/{id} | — | ✓ | |
DELETE /benefits/{id} | — | ✓ | Sets status → inactive |
Endpoints
POST /benefits
Admin only. Create a benefit. Provider must exist and be active.
GET /benefits
List benefits. JWT users see only
active ones. Filter by provider_id, benefit_type, status.GET /benefits/{benefit_id}
Fetch a benefit by UUID. JWT users receive 404 for inactive benefits.
PATCH /benefits/{benefit_id}
Admin only. Update
name, benefit_details, or status.DELETE /benefits/{benefit_id}
Admin only. Soft-delete (
status → inactive).Request / Response Examples
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 type mismatch |
BE-504 | 404 | Benefit provider not found or inactive |
BE-505 | 400 | Validation error (e.g. empty name) |