API Overview

Base URLs

Environment	Base URL	Purpose
Local	`http://localhost:8080`	Development
Sandbox	`https://sandbox.api.aarokya.in`	Integration testing
Production	`https://api.aarokya.in`	Live environment

All endpoints accept and return application/json unless otherwise noted (the /health probe returns plain text).

Authentication

Every protected endpoint is authenticated with a bearer JWT:

Authorization: Bearer <jwt>

App-user tokens are issued by POST /auth/token — a partner platform’s backend authenticates as its service account and exchanges a worker’s phone number (and, on first contact, an id-proof) for a short-lived app JWT:

Response 200 — POST /auth/token

{
  "user_id": "047382910564",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Admin and service tokens are minted by Keycloak via OIDC. See the Authentication guide for the full token lifecycle, claims, and renewal model.

Public endpoints (no auth required)

Method	Path	Notes
`GET`	`/health`	Health check for load balancers — returns plain text

POST /auth/token itself is not public — the caller must present a platform service-account bearer token.

Common Headers

Request Headers

Header	Required	Description
`Content-Type`	Yes (for POST/PATCH)	Always `application/json`
`Authorization`	Yes (protected endpoints)	`Bearer <jwt>`

Response Headers

Header	Description
`Content-Type`	`application/json` for data and error responses

Request Format

curl https://api.aarokya.in/users/<user_id> \
  -H 'Authorization: Bearer <jwt>'

curl -X POST https://api.aarokya.in/auth/token \
  -H 'Authorization: Bearer <platform_service_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "9876543210",
    "phone_country_code": "+91",
    "id_proof": { "proof_type": "AADHAAR", "number": "123456789012" }
  }'

curl -X PATCH https://api.aarokya.in/users/<user_id> \
  -H 'Authorization: Bearer <jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"first_name": "Priya"}'

Response Envelope

Successful responses return the resource (or a list envelope) as JSON directly — there is no outer success wrapper. Error responses use a consistent error envelope — see the Error Reference.

{
  "user_id": "047382910564",
  "phone_number": "9876543210",
  "first_name": "Priya",
  "status": "ACTIVE"
}

{
  "data": [ ],
  "total": 45,
  "limit": 20,
  "offset": 0
}

{
  "error": {
    "type": "invalid_request",
    "message": "Invalid or expired token",
    "code": "AUE_301"
  }
}

Pagination

List endpoints (e.g. /accounts, /consultations, /insurance_policies) use offset-based pagination via two optional query parameters:

Parameter	Type	Description
`limit`	integer	Maximum items per page
`offset`	integer	Number of items to skip before the page

Paginated responses are a flat envelope carrying the page and the total count:

{
  "data": [ ],
  "total": 45,
  "limit": 20,
  "offset": 0
}

The data array holds the page; total is the full count matching the query (use it with limit/offset to drive page controls).

Health Check

GET /health

Returns 200 OK with no authentication required. Used by load balancers, uptime monitors, and Kubernetes readiness probes. The body is a plain-text status string.

Where to Go Next

Authentication

Bearer JWTs, POST /auth/token, claims, and token renewal.

Error Reference

The error envelope, HTTP status conventions, and the per-domain code catalogue.

Modules

Endpoint-by-endpoint reference for every domain (users, accounts, consultations, insurance, and more).

API Reference

Try It Out

Base URLs

Authentication

Public endpoints (no auth required)

Common Headers

Request Headers

Response Headers

Request Format

Response Envelope

Health Check

Where to Go Next

Authentication

Error Reference

Modules

​Base URLs

​Authentication

​Public endpoints (no auth required)

​Common Headers

​Request Headers

​Response Headers

​Request Format

​Response Envelope

​Pagination

​Health Check

​Where to Go Next

Authentication

Error Reference

Modules

Base URLs

Authentication

Public endpoints (no auth required)

Common Headers

Request Headers

Response Headers

Request Format

Response Envelope

Pagination

Health Check

Where to Go Next