1. Access model
Production mobile API requests carry two independent proofs: an official-app proof and a user Bearer token. Public health, rollout status and OpenAPI schema routes do not require a user account. Rollout modes can temporarily monitor rather than reject missing user tokens.
| Proof | Header | What it establishes |
|---|---|---|
| Application trust token | X-Sarathi-App-Token plus request-signature headers | Registered official app installation and body-bound request |
| User access JWT | Authorization: Bearer … | Authenticated user session bound to the installation |
2. WhatsApp OTP and session routes
| Method and path | Purpose |
|---|---|
POST /api/v1/auth/otp/request | Send a short-lived WhatsApp OTP challenge. |
POST /api/v1/auth/otp/verify | Verify code, accept current terms and create a persistent rotating session. |
POST /api/v1/auth/token | Rotate a refresh token and issue a new short access JWT. |
GET /api/v1/auth/me | Return the minimal authenticated account summary. |
POST /api/v1/auth/logout | Revoke the current session. |
DELETE /api/v1/auth/account | Delete the account and authentication sessions. |
Refresh tokens belong only in protected device storage. Never place them in a URL, analytics event, application log or support message.
3. Main endpoint groups
| Group | Examples |
|---|---|
| Journey planning | POST /api/v1/journeys/plan, POST /api/plan |
| Stops and access | GET /api/v1/stops/access, GET /api/stops/nearby |
| Bus and Metro directory | GET /api/routes, GET /api/metro/lines, GET /api/metro/stations |
| Places | GET /api/places/autocomplete, GET /api/places/details |
| Data and health | GET /api/v1/datasets/current, GET /api/v1/live, GET /api/v1/ready |
| App trust | POST /api/v1/trust/challenge, POST /api/v1/trust/register, POST /api/v1/trust/token |
4. Rate limits
The generic API limit is intentionally broad. Journey planning, place lookup, feedback and authentication have narrower buckets. OTP has additional per-phone, per-IP, resend, daily and verification-attempt limits. A 429 response includes Retry-After; callers should wait and use exponential backoff rather than retrying in a loop.
5. Errors and request references
Most validation and security failures use a JSON detail object with a stable code and user-safe message. Authentication errors return WWW-Authenticate: Bearer. Trust and auth responses use dedicated diagnostic headers. Include the API request ID, not a token or OTP, when reporting an error.
6. Complete schema
Use the generated OpenAPI JSON schema for current models, parameters and responses. The root Compose proxy serves the schema from the same origin as this page.
Production integrations require explicit owner approval, a quota decision and a security review. The mobile app credential model is not a general third-party API key mechanism.