Benefit Provider Module

Auth guard: all endpoints require a first-party Keycloak OIDC bearer token (Authorization: Bearer <token>). Provider CRUD is open to any trusted-backend actor (admin or benefit-provider, human or service); the credentials and dashboard-user sub-resources are scoped per provider (admin, or a benefit-provider human user belonging to that provider). No app-user (mobile JWT) path.

Overview

A benefit provider is a company or entity (e.g. a diagnostic chain, insurer, or telemedicine platform) that offers one or more benefits to Aarokya users. Providers are the top-level catalogue entry — every Benefit row has a provider_id FK referencing a provider.

Name uniqueness is global. No two active providers may share the same name. Soft-deleted providers free their name immediately (status flips to INACTIVE).
Delete is guarded. A provider with any associated benefit (active or inactive) cannot be deleted — soft-delete the benefits first.
Each provider can mint machine credentials (Basic-auth tokens backed by a Keycloak service-account client) and provision dashboard users scoped to itself.

Data Flow

Auth Guards by Endpoint

Endpoint	Guard	Who passes
`POST /benefit_providers`	`require_trusted_backend(false)`	Admin or benefit-provider (human/service)
`GET /benefit_providers`	`require_trusted_backend(true)`	Above, plus read-only admin
`GET /benefit_providers/{benefit_provider_id}`	`require_benefit_provider_strict(true, id)`	Admin, or BP actor scoped to this provider
`PATCH /benefit_providers/{benefit_provider_id}`	`require_trusted_backend(false)`	Admin or benefit-provider (human/service)
`DELETE /benefit_providers/{benefit_provider_id}`	`require_trusted_backend(false)`	Admin or benefit-provider (human/service)
`POST` / `GET` / `DELETE` `…/credentials`	`require_benefit_provider_user_strict`	Admin, or BP human user scoped to this provider
`POST` / `GET` / `DELETE` `…/users`	`require_benefit_provider_user_strict`	Admin, or BP human user scoped to this provider

Provider Endpoints

POST /benefit_providers

Create a provider. Requires name (globally unique) and a URL-safe slug.

GET /benefit_providers

Paginated list. Filter by status; supports sort_on/sort_by, start_time/end_time, limit/offset.

GET /benefit_providers/{id}

Fetch a single provider by UUID.

PATCH /benefit_providers/{id}

Rename a provider. Only name is updatable; slug is immutable. New name must not conflict.

DELETE /benefit_providers/{id}

Soft-delete (status → INACTIVE). Fails with 409 if the provider has benefits.

slug is a lowercase URL/Keycloak-safe identifier ([a-z0-9-], 2–40 chars) used as part of the service-account clientId. It is set at creation and is immutable thereafter.

Credentials Sub-resource

Each provider can hold multiple machine credentials. A credential is a Keycloak service-account client returning a basic_token (HTTP Basic auth) the provider’s backend uses to call Aarokya.

POST /benefit_providers/{id}/credentials

Mint a new credential. The basic_token is returned once and is never retrievable afterwards.

GET /benefit_providers/{id}/credentials

List credential_ids for this provider. Never returns secrets.

DELETE /benefit_providers/{id}/credentials/{credential_id}

Revoke one credential. Idempotent: revoked: false if no such credential existed.

Creating credentials always mints a fresh credential_id — there is no idempotency and no 409. The basic_token is shown only in the create response; store it immediately. There is no path that re-reads it.

Dashboard Users Sub-resource

Provision human dashboard users scoped to a single provider.

POST /benefit_providers/{id}/users

Provision a dashboard user (email, first_name, last_name). The temporary_password is shown once.

GET /benefit_providers/{id}/users

List dashboard users scoped to this provider.

DELETE /benefit_providers/{id}/users/{keycloak_user_id}

Disable a dashboard user. Idempotent: disabled: false if no matching user.

Request / Response Examples

curl -X POST http://localhost:8080/benefit_providers \
  -H 'Authorization: Bearer eyJhbGci...oidc-token...' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Narayana Health", "slug": "narayana-health" }'

{
  "id": "018f4c2a-1b3e-7d8f-9a0b-2c3d4e5f6a7b",
  "name": "Narayana Health",
  "slug": "narayana-health",
  "status": "ACTIVE",
  "created_at": "2026-04-12T10:00:00Z",
  "last_modified_at": "2026-04-12T10:00:00Z"
}

{
  "credential_id": "018f4c2a-9c0d-7e1f-aa2b-3c4d5e6f7a8b",
  "basic_token": "<shown once — store it now>"
}

Error Codes

Code	HTTP	Description
`BPE_400`	500	Internal server error
`BPE_401`	404	Provider not found
`BPE_402`	409	Name already exists
`BPE_403`	409	Provider has associated benefits — delete benefits first
`BPE_404`	400	Validation error (e.g. empty name)
`BPE_405`	500	Keycloak is not configured for this deployment
`BPE_406`	500	Upstream Keycloak request failed

Overview

Architecture

Decisions

Modules

Benefit Provider Module

Overview

Data Flow

Auth Guards by Endpoint

Provider Endpoints

POST /benefit_providers

GET /benefit_providers

GET /benefit_providers/{id}

PATCH /benefit_providers/{id}

DELETE /benefit_providers/{id}

Credentials Sub-resource

POST /benefit_providers/{id}/credentials

GET /benefit_providers/{id}/credentials

DELETE /benefit_providers/{id}/credentials/{credential_id}

Dashboard Users Sub-resource

POST /benefit_providers/{id}/users

GET /benefit_providers/{id}/users

DELETE /benefit_providers/{id}/users/{keycloak_user_id}

Request / Response Examples

Error Codes

​Overview

​Data Flow

​Auth Guards by Endpoint

​Provider Endpoints

POST /benefit_providers

GET /benefit_providers

GET /benefit_providers/{id}

PATCH /benefit_providers/{id}

DELETE /benefit_providers/{id}

​Credentials Sub-resource

POST /benefit_providers/{id}/credentials

GET /benefit_providers/{id}/credentials

DELETE /benefit_providers/{id}/credentials/{credential_id}

​Dashboard Users Sub-resource

POST /benefit_providers/{id}/users

GET /benefit_providers/{id}/users

DELETE /benefit_providers/{id}/users/{keycloak_user_id}

​Request / Response Examples

​Error Codes

Overview

Data Flow

Auth Guards by Endpoint

Provider Endpoints

Credentials Sub-resource

Dashboard Users Sub-resource

Request / Response Examples

Error Codes