> ## Documentation Index
> Fetch the complete documentation index at: https://hmis-docs.derrickmugabwa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Patient mobile API guide

> OTP authentication, ownership controls, token abilities, and endpoint coverage for the patient app.

The patient mobile API currently has 24 operations designed for a first-party mobile application. Every protected response is restricted to the patient linked to the authenticated device token.

## OTP sign-in flow

1. The patient enters the phone number recorded during registration.
2. Call **Request OTP**. The response is intentionally generic so callers cannot discover whether a phone number exists.
3. Call **Verify OTP** with the phone number and code. If a phone number is shared by more than one patient, also provide the patient number and date of birth to identify the correct record.
4. Store the returned Sanctum bearer token in the operating system's secure credential storage.
5. Send the token as `Authorization: Bearer <token>` on protected requests.
6. Call **Sign out** to revoke the current device token.

OTP requests and verification attempts are rate limited. Production must bind a real SMS sender; the development log sender must not be used to deliver production codes.

## Endpoint coverage

| Area           | Operations | Includes                                                                      |
| -------------- | ---------: | ----------------------------------------------------------------------------- |
| Authentication |          3 | Request OTP, verify OTP, and sign out                                         |
| Profile        |          2 | View and update the patient's own profile                                     |
| Appointments   |          7 | Clinics, availability, list, view, book, reschedule, and cancel               |
| Health records |          8 | Visits, medical history, allergies, prescriptions, and authorized diagnostics |
| Billing        |          4 | Coverages, bills, bill details, and payments                                  |

## Token abilities

Patient tokens use a separate, narrow ability namespace:

* `patient:read`
* `patient:profile`
* `patient:appointments`
* `patient:records`
* `patient:billing`

An ability does not bypass ownership checks. A patient cannot request another patient's appointment, visit, result, bill, or payment by changing an identifier.

## Clinical privacy

The medical-history endpoint gives the app one stable summary of the patient's longitudinal history. Separate endpoints remain available for lists that need their own pagination or interaction, such as prescriptions and diagnostic results.

Only patient-authorized diagnostic results are returned. Internal notes, drafts, processing errors, operational metadata, and staff-only fields are excluded from patient resources.

## Current scope

The API fits the initial mobile scope: identity, self-service appointments, outpatient history, authorized results, insurance coverage, and billing visibility. Inpatient records, wallets, device management, payment initiation, and public website appointment booking are deferred. Those features should extend the versioned API without changing the ownership and token model documented here.