Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sagar-grv/ayush-synapse/llms.txt

Use this file to discover all available pages before exploring further.

Ayush Synapse uses JWT (HS256) for authentication. In demo mode, any caller can obtain a token from POST /auth/login — no credentials or prior registration is needed. The returned token must then be included in the Authorization header of all protected endpoint requests.

​
POST /auth/login

Generates a signed JWT token for the supplied user identity and role.
PropertyValue
MethodPOST
Path/auth/login
Auth requiredNo
Content-Typeapplication/json

​
Request Body

​
user_id
string
default:"demo_user"
An identifier for the requesting user. Any non-empty string is accepted in demo mode. Echoed back in the response.
​
role
string
default:"clinician"
The role to embed in the token. Controls permission checks on protected endpoints.Accepted values: clinician, admin

​
Response Fields

​
message
string
Always "Authentication successful" on a valid request.
​
token
string
The signed JWT string. Pass this value in the Authorization: Bearer header of subsequent requests.
​
user_id
string
The user_id value echoed from the request body (or "demo_user" if omitted).
​
role
string
The role embedded in the token ("clinician" or "admin").
​
permissions
object
A set of boolean flags describing what this token authorises.
​
demo_mode
boolean
true when the server is running with DEMO_MODE=True. Indicates that all features are accessible regardless of role.

​
Example Request

curl -X POST http://localhost:5000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"user_id": "dr_sharma", "role": "clinician"}'

​
Example Response

{
  "message": "Authentication successful",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiZHJfc2hhcm1hIiwicm9sZSI6ImNsaW5pY2lhbiIsImV4cCI6MTcwMDAwMDAwMCwiaWF0IjoxNjk5OTEzNjAwfQ.SIGNATURE",
  "user_id": "dr_sharma",
  "role": "clinician",
  "permissions": {
    "can_access_all_endpoints": true,
    "can_view_all_data": true,
    "can_perform_translations": true,
    "can_access_fhir_resources": true
  },
  "demo_mode": true
}

​
Using the Token

Include the token from the login response as a Bearer credential in the Authorization header of every protected request. 
Authorization: Bearer <token>

curl -X GET http://localhost:5000/namaste \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Qi..."

​
Token Expiry

Tokens are valid for 24 hours from the time of issue (iat claim). After expiry, the API returns: 
{
  "error": "Token has expired"
}
Re-authenticate by calling POST /auth/login again. There is no refresh-token flow; a new full login is required.

​
Error Responses

HTTP StatusConditionResponse body
401Authorization header is absent{"error": "Authorization header is required"}
401Header format is not Bearer <token>{"error": "Invalid Authorization header format"}
401Token signature is invalid or malformed{"error": "Invalid token"}
401Token has passed its 24-hour expiry{"error": "Token has expired"}
403Token is valid but role does not meet endpoint requirement{"error": "Access denied. Required role: <role>"}
The default JWT_SECRET_KEY shipped in .env.example (namaste-icd11-mvp-demo-secret-key-2025) is public knowledge. Never use this value in a public or production deployment. Generate a cryptographically random secret and set it via the JWT_SECRET_KEY environment variable before exposing the API to any network.
# Generate a strong key (Linux / macOS)
python -c "import secrets; print(secrets.token_hex(32))"

Build docs developers (and LLMs) love

Get started for freeTalk to us