"description": "# API spec for Simple Server\n## Sync APIs\nThis API spec documents the endpoints that the devices (that are offline to varying levels) will use to sync data. The sync end points will send and receive bulk (a list of) entities. Both sending and receiving can be batched with configurable batch-sizes to accommodate low network bandwidth situations.\n\n## Nesting resources\nThe APIs have been designed to provide an optimal balance between accuracy and simplicity. Some of the APIs (patients) will be nested, and some other (blood pressures) will be flat.\n\n## Sync Mechanism\nRefer to the [related ADR](https://github.com/simpledotorg/simple-server/blob/master/doc/arch/001-synchronization.md).\n\n## API Authentication\nThere are two types of authentication available to access different parts of the Simple API.\n- User Authentication - For medical professionals using the Simple App. Grants access to most of the Simple API\n to read and write data for communities of patients.\n- Patient authentication - For individual patients. Grants access to read a patient's own data.\n\n### User Authentication\n\nA Simple client can make authenticated requests to the Simple API on behalf of a medical professional with the\nfollowing three required credentials:\n- API Access Token\n- User ID\n- Facility ID\n\nIn order to obtain these credentials, a Simple client can authenticate a user with the following steps. The\nclient will need the user's registered phone number to perform the authentication.\n1. Submit the users phone number to the [`POST /v4/users/find` endpoint](#tag/User/paths/~1users~1find/post). If\na user exists with this phone number, the response will return their id.\n2. Submit the user's id retreived in the previous step, along with the user's password to the\n[`POST v4/users/activate` endpoint](#tag/User/paths/~1users~1activate/post).\nThis will validate the user's password, and trigger an OTP to be sent to the user's phone number.\n3. Submit the user's id, their password, and the OTP (received after the previous step) to the\n[`POST v3/login` endpoint](#tag/User-Login/paths/~1login/post). If the submitted otp and password are valid,\nthis will return an access token that can be used to authenticate the user. The access token will remain valid\nuntil the user signs into another device.\n\nOn successful authentication, the client will receive a payload containing an API access token and some user\ninformation.\nThe following headers need to be attached to subsequent requests as shown below.\n- `Authorization: Bearer <access token>`\n- `X-User-Id: <user ID>`\n- `X-Facility-Id: <facility ID>` This is the id for either the registration facility of the user, or another\nfacility in their facility group.\n\n### Patient Authentication\nA Simple client can make authenticated requests to the Simple API on behalf of a patient with the following\ncredentials:\n- API Access Token\n- Patient ID\n\nIn order to obtain these credentials, a Simple client can authenticate a patient with the following steps. The\nclient will need the patient's BP Passport UUID to perform the authentication.\n1. Submit the patient's BP Passport UUID to the [`POST /v4/patients/activate` endpoint](#tag/Patient/paths/~1patient~1activate/post).\n This will trigger an OTP message to be sent to the patient's registered phone number.\n2. Submit the patient's BP Passport UUID and OTP (received after the previous step) to the [`POST /v4/patients/login` endpoint](#tag/Patient/paths/~1patient~1login/post)\n\nOn successful authentication, the client will receive a payload containing an API access token and a patient ID.\nBoth of these data points need to be attached to subsequent requests as request headers as shown below.\n- `Authorization: Bearer <access token>`\n- `X-Patient-Id: <patient ID>`\n\nThe API access token will remain valid until the patient signs into another device.\n\nThe comprehensive list of authentication mechanisms used is provided below. It lists the specific details of\nusing access tokens and other request headers to authenticate with the API.\n",
0 commit comments