Auth guard:
POST /auth/token takes a bearer JWT minted for a platform service account (actor_type: platform_service) via actor.require_platform_service() — admins, dashboard users, and end-user tokens are rejected, and the platform_id is taken from the token claim, never the body. POST /auth/platform_token takes only the platform-less token OTP login issues (an AppUser with no platform_id).Overview
Aarokya does not own user authentication — that belongs to the partner app (e.g. Namma Yatri). The partner backend authenticates as its platform service account, then callsPOST /auth/token with a verified phone number and id-proof and receives a short-lived app JWT scoped to that user. The app JWT is stateless and self-contained.
The standalone app has no partner backend: the user signs in by OTP, picks one of their platforms, and exchanges the OTP token for the same platform-scoped app JWT at POST /auth/platform_token — see OTP Login → Platform Token below.
The platform service-account bearer is obtained out-of-band: an admin provisions a credential via POST /platforms/{platform_id}/credentials, which returns a basic_token. The platform exchanges that basic_token with Keycloak (client_credentials grant) for the service-account JWT it presents here. See the Platform module for credential provisioning.
Token Issuance Flow
OTP Login → Platform Token
Find-or-Create Semantics
Lookup is by
(phone_country_code, phone_number) against active users — it is not keyed on platform_id. The platform_id from the token is validated and embedded in the issued app token’s claims.App JWT Claims
The issuedaccess_token is an RS256 app token. Its claims flatten an app actor block alongside standard iss / aud / iat / exp:
Endpoints
POST /auth/token
Issue an app JWT for a user. Creates the user on first call. Requires a platform service-account bearer token.
POST /auth/platform_token
Exchange the OTP login token for an app JWT scoped to one of the user’s platforms.
Request / Response Example
id_proof is optional; proof_type accepts AADHAAR, PAN, PASSPORT,
DRIVING_LICENSE, or VOTER_ID. Alongside it the call takes the optional profile
fields first_name, last_name, email, occupation, gender, dob and
address, all persisted on the create path only.
id_proof is written by this endpoint (create path only — it is ignored on
re-auth), by PATCH /users/{user_id}, and optionally by /add_details, where
a supplied value replaces the stored one. It is stored as a
single users.id_proof text column encoded <type>:<number>.