Authentication

Individual Authentication

Authenticate individuals (patients) using a simple, secure OTP-based flow. No passwords to remember — just their phone number.

How it works

1. Request an OTP to be sent to the patient’s phone
2. Patient receives the OTP via SMS
3. Verify the OTP to get an access token
4. Use the token for subsequent requests

Request OTP

Send a one-time password to the patient’s phone number.

# Request OTP
request_patient_otp({ phone: "+2348012345678" })

Parameters:

Parameter	Type	Required	Description
phone	string	Yes	Phone number in international format (e.g., +2348012345678)

Response:

{
  "success": true,
  "message": "OTP sent successfully",
  "expiresIn": 600
}

Verify OTP

Verify the OTP and receive an access token.

# Verify OTP
verify_patient_otp({
  phone: "+2348012345678",
  otp: "123456"
})

Parameters:

Parameter	Type	Required	Description
phone	string	Yes	Same phone number used to request OTP
otp	string	Yes	6-digit code from SMS

Response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "USER-123",
    "name": "John Doe",
    "phone": "+2348012345678"
  }
}

Create Account (New Users)

If the phone number isn’t registered yet, create a new account.

# Create new patient account
create_patient({
  name: "John Doe",
  phone: "+2348012345678",
  email: "john@example.com"
})

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Full name of the patient
phone	string	Yes	Phone number in international format
email	string	No	Optional email address

Example: Complete Authentication Flow

# Step 1: Request OTP
request_patient_otp({ phone: "+2348012345678" })
# → OTP sent to phone

# Step 2: Verify OTP (user enters code from SMS)
verify_patient_otp({
  phone: "+2348012345678",
  otp: "123456"
})
# → Returns access token

# Step 3: Use token for authenticated requests
# (Token is automatically handled by the MCP client)

Error Handling

Error	Cause	Solution
INVALID_PHONE	Phone format incorrect	Use international format (+234…)
OTP_EXPIRED	Code expired (10 min)	Request new OTP
INVALID_OTP	Wrong code entered	Check SMS and retry
MAX_ATTEMPTS	Too many failed tries	Wait 30 minutes

Next steps

• Search Medications — Find medications after logging in
• Place Order — Order medications
• Provider Authentication — For healthcare platforms