Auth guard: bearer JWT (
Authorization: Bearer <jwt>). Platform CRUD requires an admin actor; GET /platforms also admits an app token, scoped to its own platforms. Per-tenant credential and dashboard-user sub-resources also admit a platform user scoped to the same platform_id.Overview
A platform is a logical tenant — it represents a partner app integrated with Aarokya (e.g. Namma Yatri, a hospital chain). Each platform can hold one or more service-account credentials (used by the partner backend to mint tokens) and one or more dashboard users (humans who manage the tenant). End-users authenticated viaPOST /auth/token carry the issuing platform_id in their token. One user can belong to several platforms — each login writes a platform_users row for that pair.
- Name uniqueness is scoped to active platforms. A deleted platform’s name can be reused.
slugis immutable. Set at creation, lowercase[a-z0-9-]{2,40}, used to build the Keycloak service-accountclientId.addressis required on create. A structured address object (line1,line2,city,state,pincode,country). It is the tenant-level fallback address printed on insurance documents when a user under this platform has no address of their own — because it is mandatory, an insurance address always resolves. Required onPOST /platforms; optional onPATCH(omitting it leaves the stored value unchanged).bank_detailsis required on create. The platform’s origin bank (ifsc_code+account_number). It is persisted as the platform’s ownaccountsrow (holder = platform:<id>,account_type = SAVINGS) in the same transaction as the platform, and quoted as the source bank of a customer-tip deposit — which is what makes the ledger book that money to a user’s others pool rather than their own. Not echoed onPlatformResponseand not updatable; read it fromGET /accounts?holder=platform:<id>.- Soft delete via status. Deleting a platform sets
status → INACTIVE; it does not remove the row.
Platform in the Auth Flow
A platform is created with no credentials. An admin (or a platform user scoped to the tenant) provisions a credential viaPOST /platforms/{platform_id}/credentials, which mints a Keycloak service-account client and returns a basic_token once. The partner backend exchanges that basic_token with Keycloak (client_credentials) for a platform_service bearer JWT, which it then uses to call POST /auth/token.
Auth Guards by Endpoint
Endpoints
Platform CRUD
POST /platforms
Create a new platform (
name + slug). Returns 201. No credentials are minted yet.GET /platforms
Paginated list. Filter by
status and platform_ids. An app token sees only its own platforms.GET /platforms/{id}
Fetch a single platform by UUID.
PATCH /platforms/{id}
Update a platform’s
name and/or address. A new name must not conflict.DELETE /platforms/{id}
Soft-delete a platform (
status → INACTIVE).Service-account credentials
POST /platforms/{id}/credentials
Mint a new credential. Returns
basic_token once — store it now.GET /platforms/{id}/credentials
List
credential_ids for the platform. Never returns secrets.DELETE /platforms/{id}/credentials/{credential_id}
Revoke one credential. Idempotent (
revoked: false if absent).Dashboard users (per-tenant)
POST /platforms/{id}/users
Provision a dashboard user.
temporary_password shown once.GET /platforms/{id}/users
List dashboard users scoped to this platform.
DELETE /platforms/{id}/users/{keycloak_user_id}
Disable a dashboard user. Idempotent.
Request / Response Examples
An app token sees a platform only while it has an
ACTIVE platform_users row there, and only the platform its token was issued for. The token’s platform wins over platform_ids: naming another platform does not widen the list.