Member Portal API
Stateless Backend-for-Frontend (BFF) — aggregates data from downstream services for the member-facing web portal and mobile app.
Overview
The Member Portal API is a stateless BFF that provides a single, member-scoped API surface for the Olly member portal and mobile application. It has no database of its own — every response is composed by calling one or more downstream services and returning the result to the client.
All routes are scoped to the authenticated member. The memberScopeMiddleware extracts the partyLocator from the JWT's sub claim (or a custom partyLocator claim) and injects it into the request context. Handlers use this locator to call downstream services, ensuring a member can only access their own data.
The BFF pattern keeps the member-facing API stable and simple while allowing the underlying service topology to evolve. Changes to Eligibility, Claims, or Consent APIs are absorbed by updating the BFF rather than the mobile client.
Responsibilities
- Authenticate members via Keycloak JWT and scope all requests to their
partyLocator - Proxy coverage and accumulator queries to Eligibility
- Proxy claim submission and retrieval to Claims
- Proxy document listing and retrieval to Document Service
- Proxy profile reads and updates to Policy Admin
- Proxy notification preference reads and updates to Notifications
- Proxy consent reads and updates to Consent
Database
No database. The Member Portal API is fully stateless. It holds no data and runs no migrations.
API Routes
All routes require JWT authentication. The member's partyLocator is extracted from the JWT — no route parameter is needed.
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /me/coverage | JWT | Get the member's active coverage |
GET | /me/accumulators | JWT | Get the member's accumulator balances |
GET | /me/claims | JWT | List the member's claims |
POST | /me/claims | JWT | Submit a new claim |
GET | /me/claims/{locator} | JWT | Get a specific claim |
GET | /me/documents | JWT | List the member's documents (EOBs, policy docs, etc.) |
GET | /me/documents/{locator} | JWT | Retrieve a specific document (returns PDF) |
GET | /me/profile | JWT | Get the member's profile (party details) |
PATCH | /me/profile | JWT | Update the member's profile |
GET | /me/preferences | JWT | Get the member's notification preferences |
PUT | /me/preferences | JWT | Update notification preferences |
GET | /me/consent | JWT | Get the member's current consent state |
PUT | /me/consent | JWT | Update consent preferences |
Events
Publishes
The Member Portal API does not publish any Kafka events.
Consumes
The Member Portal API does not consume any Kafka events.
Dependencies
| Service | How used |
|---|---|
| Eligibility | GET /me/coverage and GET /me/accumulators |
| Claims | GET /me/claims, POST /me/claims, GET /me/claims/{locator} |
| Document Service | GET /me/documents, GET /me/documents/{locator} |
| Policy Admin | GET /me/profile, PATCH /me/profile |
| Notifications | GET /me/preferences, PUT /me/preferences |
| Consent | GET /me/consent, PUT /me/consent |
Key Design Decisions
Stateless by design: The BFF deliberately avoids owning any state. This simplifies deployment (any instance can serve any request), eliminates database migration concerns, and means the BFF can be scaled independently of data-owning services.
Error mapping: Client errors from downstream services are mapped to appropriate HTTP status codes: ErrNotFound → 404, ErrUpstream → 502, others → 500. This provides consistent error semantics to the mobile client regardless of which downstream service failed.