Platform Module

Auth guard: bearer JWT (Authorization: Bearer <jwt>). Platform CRUD requires an admin actor; 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 via POST /auth/token carry the issuing platform_id in their token.

Name uniqueness is scoped to active platforms. A deleted platform’s name can be reused.
slug is immutable. Set at creation, lowercase [a-z0-9-]{2,40}, used to build the Keycloak service-account clientId.
address is 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 on POST /platforms; optional on PATCH (omitting it leaves the stored value unchanged).
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 via POST /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

Endpoint	Guard	Notes
`POST /platforms`	Admin	Name must be unique among active platforms
`GET /platforms`	Admin (read-only admin OK)	Filter by `status`
`GET /platforms/{id}`	Admin, or platform actor for this `id`
`PATCH /platforms/{id}`	Admin	`name` and/or `address` updatable
`DELETE /platforms/{id}`	Admin	Sets `status → INACTIVE`
`POST /platforms/{id}/credentials`	Admin, or platform user for this `id`	Mints a new credential each call
`GET /platforms/{id}/credentials`	Admin, or platform user for this `id`	Lists credential ids only
`DELETE /platforms/{id}/credentials/{cred_id}`	Admin, or platform user for this `id`	Idempotent
`POST /platforms/{id}/users`	Admin, or platform user for this `id`	Provisions a dashboard human
`GET /platforms/{id}/users`	Admin, or platform user for this `id`
`DELETE /platforms/{id}/users/{keycloak_user_id}`	Admin, or platform user for this `id`	Idempotent

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.

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

curl -X POST http://localhost:8080/platforms \
  -H 'Authorization: Bearer <admin-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Namma Yatri",
        "slug": "namma-yatri",
        "address": {
          "line1": "3rd Floor, Tower B, Prestige Tech Park",
          "line2": "Marathahalli",
          "city": "Bengaluru",
          "state": "Karnataka",
          "pincode": "560103",
          "country": "IN"
        }
      }'

{
  "id": "0190b6c2-7e3a-7c6e-9b1d-2f4a8c1e5d33",
  "name": "Namma Yatri",
  "slug": "namma-yatri",
  "status": "ACTIVE",
  "address": {
    "line1": "3rd Floor, Tower B, Prestige Tech Park",
    "line2": "Marathahalli",
    "city": "Bengaluru",
    "state": "Karnataka",
    "pincode": "560103",
    "country": "IN"
  },
  "created_at": "2026-04-12T10:00:00Z",
  "last_modified_at": "2026-04-12T10:00:00Z"
}

curl -X POST http://localhost:8080/platforms/0190b6c2-7e3a-7c6e-9b1d-2f4a8c1e5d33/credentials \
  -H 'Authorization: Bearer <admin-jwt>'

{
  "credential_id": "0190b6c2-9a11-7c6e-9b1d-2f4a8c1e5d44",
  "basic_token": "cGxhdGZvcm0tbmFtbWEteWF0cmkt..."
}

basic_token is returned only by POST /credentials and is never retrievable again. GET /credentials returns credential_ids only — no secrets.

Error Codes

Code	HTTP	Description
`PE_200`	500	Internal server error
`PE_201`	404	Platform not found
`PE_202`	409	Name already exists
`PE_203`	400	Validation error (e.g. empty name)
`PE_204`	500	Keycloak is not configured for this deployment
`PE_205`	500	Upstream Keycloak request failed

Overview

Architecture

Decisions

Modules

Platform Module

Overview

Platform in the Auth Flow

Auth Guards by Endpoint

Endpoints

Platform CRUD

POST /platforms

GET /platforms

GET /platforms/{id}

PATCH /platforms/{id}

DELETE /platforms/{id}

Service-account credentials

POST /platforms/{id}/credentials

GET /platforms/{id}/credentials

DELETE /platforms/{id}/credentials/{credential_id}

Dashboard users (per-tenant)

POST /platforms/{id}/users

GET /platforms/{id}/users

DELETE /platforms/{id}/users/{keycloak_user_id}

Request / Response Examples

Error Codes

​Overview

​Platform in the Auth Flow

​Auth Guards by Endpoint

​Endpoints

​Platform CRUD

POST /platforms

GET /platforms

GET /platforms/{id}

PATCH /platforms/{id}

DELETE /platforms/{id}

​Service-account credentials

POST /platforms/{id}/credentials

GET /platforms/{id}/credentials

DELETE /platforms/{id}/credentials/{credential_id}

​Dashboard users (per-tenant)

POST /platforms/{id}/users

GET /platforms/{id}/users

DELETE /platforms/{id}/users/{keycloak_user_id}

​Request / Response Examples

​Error Codes

Overview

Platform in the Auth Flow

Auth Guards by Endpoint

Endpoints

Platform CRUD

Service-account credentials

Dashboard users (per-tenant)

Request / Response Examples

Error Codes