Auth guard: api-key header (external partner key). Partners cannot call admin endpoints. Admin cannot call this endpoint.

​
Overview

Aarokya does not own user authentication — that belongs to the partner app (e.g. Namma Yatri). The partner backend calls POST /auth/token with a verified phone number and receives a short-lived JWT scoped to that user. This is the only auth endpoint; there are no refresh tokens, OTP flows, or session management.

​
Token Issuance Flow

​
Find-or-Create Semantics

ScenarioBehaviour
First call for this phone + platformCreates user with status = onboarding, returns token
Subsequent callsReturns fresh token for existing user, reflects current status
User is deactivatedReturns error — deactivated users cannot receive tokens

​
JWT Claims

{
  "sub": "047382910564",
  "status": "ONBOARDING",
  "iat": 1718000000,
  "exp": 1718086400
}
ClaimDescription
subUser ID — pass in {user_id} path params for all user-scoped calls
statusonboarding or active — drive onboarding UI from this
expConfigurable via jwt.expiry_hours; call token again when expired

​
Endpoints

POST /auth/token

Issue a JWT for a user. Creates the user on first call. Requires partner api-key header.

​
Request / Response Example

curl -X POST http://localhost:8080/auth/token \
  -H 'api-key: your-partner-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "9876543210",
    "phone_country_code": "+91",
    "id_proof": {
      "proof_type": "AADHAAR",
      "number": "123456789012"
    }
  }'

​
Error Codes

CodeHTTPDescription
AUE-300500Internal server error
AUE-301401Invalid or expired token
AUE-302401Invalid API key
AUE-303403User account is not active
AUE-304400Invalid platform ID format
AUE-305400Platform not found
AUE-306400Platform is inactive
AUE-307422Onboarding already complete