Auth guards vary by endpoint — JWT users can only access their own record. Admin key has full access.
Overview
User rows are created by the Auth module on firstPOST /auth/token. This module owns everything after creation: profile reads and writes, the onboarding transition, and soft-deletion. Phone number and user ID are immutable once set.
Onboarding Flow
New users start withstatus = ONBOARDING. Calling POST /users/{user_id}/add_details transitions them to ACTIVE and returns a fresh JWT.
Every add_details field is optional and is merged over what POST /auth/token already stored. Onboarding completes once first_name, gender and dob are all present; until then the call returns 400 naming the missing fields and writes nothing, so the client can re-submit. last_name, email, occupation, id_proof, address and bank_details (ifsc_code + account_number) are optional — bank_details also creates the user’s SAVINGS account. Salutation is deduced from gender, never sent. Completing onboarding also creates the system-managed SELF dependant.
PATCH /users/{user_id} is not part of the onboarding path — an app user can only PATCH once they are ACTIVE. While ONBOARDING, profile fields are submitted through add_details.Auth Guards by Endpoint
GET /users/{user_id} currently has no owner assertion at the handler or core layer — any authenticated caller who knows a user_id can read that profile. Treat ownership scoping as enforced only on the write and onboarding paths.Searching & Filtering Users
GET /users accepts optional, AND-combined query parameters. All three search
filters are case-insensitive prefix matches (starts-with), not substring.
Prefix means
?name=ravi matches “Ravi” and “Ravikumar” but not “Shravi”.
Search terms are sanitized to alphanumerics + spaces, and must contain at
least 3 alphanumeric characters — shorter or symbol-only terms (e.g. a blank
?name=) are ignored, not treated as match-everything.Basic details for a platform’s users
GET /users/details/basic is the GET /users search above (same parameters, minus phone,
platform_id — the platform comes from the token — and statuses — DEACTIVATED users are always left out) over one platform’s users, returning only user_id, first_name, last_name, occupation, gender
and status. A contributor uses it to find a user, then opens their goals.
The token decides what the caller can see; its values replace any x-platform-id or user_id
that names something else:
A user appears for a platform only while their
platform_users row there is ACTIVE.
Contributor — search the platform's users by name
Response 200
Endpoints
GET /users
Admin only. Paginated list of users. Filter by
statuses, creation
time_range, and search by name / phone / user_id.GET /users/details/basic
Search users with basic details only, scoped by the caller’s token.
GET /users/{user_id}
Fetch a user profile. JWT users can only fetch their own record.
PATCH /users/{user_id}
Partial profile update. Send only changed fields (
first_name, last_name, email, occupation, id_proof, dob, gender, address). App user must be ACTIVE.id_proof is write-only — it is accepted here but never returned in any response. Supplying it sets or replaces the stored one.occupation is one of DRIVER, HOUSEKEEPING_STAFF or SECURITY; any other value is a 400. Omitting a field leaves it
untouched — as with every other profile field, there is no way to clear one
back to null once set.POST /users/{user_id}/add_details
Merge the remaining profile fields and transition
status → ACTIVE once first_name, gender and dob are present. Returns fresh JWT.DELETE /users/{user_id}
Admin only. Soft-delete a user (
status → DEACTIVATED).