​
Module Map

​
Domains

Auth

Partner API keyPartners call POST /auth/token with a phone number. Aarokya creates the user on first call and issues a JWT. No OTP, no passwords.Tables: users (find-or-create)

Platform

Admin-onlyCreate and manage tenants (e.g. Namma Yatri). Every user belongs to one platform. Platform ID is required for token issuance.Tables: platforms

User

JWT + AdminFull user lifecycle — profile, onboarding, soft-delete. Self-access enforced: JWT users can only read/write their own record.Tables: users

Dependant

JWT self + AdminFamily members linked to a user. Immutable append-only rows — every update creates a new version. SELF dependant is system-managed.Tables: dependants

Benefit Provider

Admin-onlyCompanies that offer benefits. Top-level catalogue grouping. A provider must exist before any benefit can reference it.Tables: benefit_providers

Benefit

Admin write · JWT + Admin readIndividual offerings (consultation, insurance) linked to a provider. Admins manage the catalogue; active JWT users browse benefits.Tables: benefits

Account

JWT self + Partner keyStores a user’s external account references (e.g. bank account number).Tables: accounts

MRN

JWT + Partner · Admin deleteLinks a dependant to a benefit provider with an external Medical Record Number. Unique per (dependant, provider) pair.Tables: mrns

​
Authentication Model

HeaderSchemeUsed by
admin-api-keyStatic secretInternal ops — CRUD for platforms, providers, benefits
api-keyStatic secret (per partner)External partners — token issuance, account/MRN ops
Authorization: Bearer <jwt>JWT (HS256)Logged-in users — profile, dependants, accounts, MRNs
No passwords, OTP flows, or refresh tokens. When the JWT expires, the partner backend calls POST /auth/token again.

​
User Lifecycle

StatusMeaningAllowed operations
onboardingCreated, profile incompletePATCH /users/{id}, complete_onboarding
activeFully onboardedAll endpoints
deactivatedSoft-deletedNone

​
Shared Infrastructure

server_wrap

Single entry point for auth validation and error handling. Every handler calls server_wrap(auth_guard, ...) — no handler can skip auth accidentally.

Error Envelope

All errors return {"error": {"code": "...", "message": "..."}}. Switch on code (e.g. MR-903), not message.

OpenAPI / Swagger

Swagger UI at /api_docs/ui. OpenAPI JSON at /api_docs/openapi.json. Generated from code via utoipa.