Account Module

Auth: all routes use bearer JWT.

User-scoped routes (/users/{user_id}/...) require a user JWT where jwt.sub == user_id.
Admin routes (flat /accounts/...) require an admin JWT (Actor::AdminUser). Mutating an account (status, external id, details) and soft-delete are admin-only.

Overview

The accounts table holds accounts for any holder kind (today: user, sponsor; extensible). Each row carries a single holder field encoded as a URN string — user:<12-digit-id> or sponsor:<uuid>. The same encoding is used everywhere: DB storage, API responses, admin filters, audit logs. Accounts are created with status = PENDING by default and soft-deleted via admin DELETE (status flips to INACTIVE; rows are never removed).

Holder encoding

Holder	Wire format
User	`user:012345678901` (12-digit numeric)
Sponsor	`sponsor:0194e0f3-4b2a-7123-8f4a-9d5e2c8b1a3d` (UUID)

Validation runs at every entry point — JSON deserialization, DB row reads, admin query params. A malformed value returns 400 with the parse error.

Account Types

Value	Description	Legal holders
`SAVINGS`	Real-world bank account	user, sponsor
`HSA`	PBA-backed Health Savings Account	user
`EDUCATION`	PBA-backed education savings account	user
`SPONSOR`	Sponsor’s PBA normal account (funds contributions)	sponsor

(holder, account_type) legality is enforced at create time and at list-filter time. An illegal combination returns 400 (AE_807) rather than a silent empty list.

Auth Guards by Endpoint

Endpoint	Auth	Notes
`POST /users/{user_id}/accounts`	bearer (self)	User self-create
`GET /users/{user_id}/accounts`	bearer (self)	Filter by `status`, `account_type`
`GET /users/{user_id}/accounts/{id}`	bearer (self)
`GET /accounts`	admin	Filter by `holder`, `holder_kind`, `status`, `account_type`
`GET /accounts/{id}`	admin	Fetch any account by UUID
`PATCH /accounts/{id}`	admin	Update `status`, `external_account_id`, `account_details`
`DELETE /accounts/{id}`	admin	Soft-delete (status → INACTIVE)
`GET /users/{user_id}/balance`	bearer (self)	PBA balance proxy
`GET /users/{user_id}/ledger`	bearer (self)	PBA transaction ledger proxy

User-scoped routes return 403 if the path user_id does not match jwt.sub. Admin routes return 403 if the caller is not an admin.

Account Lifecycle

Soft delete only — rows persist for audit.

Admin list filters

Param	Type	Behaviour
`holder`	URN string (`user:<12d>` / `sponsor:<uuid>`)	Exact-holder filter (btree equality)
`holder_kind`	`user` \| `sponsor`	Kind-scan filter; ignored when `holder` is set
`status`	`ACTIVE` \| `INACTIVE` \| `PENDING`
`account_type`	`SAVINGS` \| `HSA` \| `EDUCATION` \| `SPONSOR`	Returns 400 if combined with a `holder` of an incompatible kind
`limit`	`i32`	default 50, max 200
`offset`	`i32`	default 0

Request / Response Examples

curl -X POST http://localhost:8080/users/047382910564/accounts \
  -H 'Authorization: Bearer eyJhbGci...' \
  -H 'Content-Type: application/json' \
  -d '{
    "external_account_id": "12345678",
    "account_type": "SAVINGS",
    "account_details": {
      "account_type": "SAVINGS",
      "ifsc_code": "HDFC0001234"
    }
  }'

{
  "id": "01926b3a-7c2e-7d4f-a1b2-c3d4e5f60040",
  "holder": "user:047382910564",
  "external_account_id": "12345678",
  "status": "PENDING",
  "account_type": "SAVINGS",
  "account_details": {
    "account_type": "SAVINGS",
    "ifsc_code": "HDFC0001234"
  },
  "created_at": "2026-04-12T10:00:00Z",
  "last_modified_at": "2026-04-12T10:00:00Z"
}

curl -G http://localhost:8080/accounts \
  -H 'Authorization: Bearer eyJhbGci...admin-jwt...' \
  --data-urlencode 'holder_kind=user' \
  --data-urlencode 'account_type=HSA'

curl -X PATCH http://localhost:8080/accounts/01926b3a-7c2e-7d4f-a1b2-c3d4e5f60040 \
  -H 'Authorization: Bearer eyJhbGci...admin-jwt...' \
  -H 'Content-Type: application/json' \
  -d '{ "status": "ACTIVE" }'

curl -X DELETE http://localhost:8080/accounts/01926b3a-7c2e-7d4f-a1b2-c3d4e5f60040 \
  -H 'Authorization: Bearer eyJhbGci...admin-jwt...'

Error Codes

Code	HTTP	Description
`AE_800`	500	Internal server error
`AE_801`	404	Account not found
`AE_802`	400	Validation error
`AE_803`	500	Upstream PBA call failed
`AE_804`	500	PBA is not configured for this environment
`AE_805`	404	No PBA-backed account exists for user
`AE_806`	404	Holder not found
`AE_807`	400	`(holder, account_type)` combination is not allowed

Overview

Architecture

Decisions

Modules

Overview

Holder encoding

Account Types

Auth Guards by Endpoint

Account Lifecycle

Admin list filters

Request / Response Examples

Error Codes

​Overview

​Holder encoding

​Account Types

​Auth Guards by Endpoint

​Account Lifecycle

​Admin list filters

​Request / Response Examples

​Error Codes

Overview

Holder encoding

Account Types

Auth Guards by Endpoint

Account Lifecycle

Admin list filters

Request / Response Examples

Error Codes