Authentication

A partner system signs in to Elix with an integration account: a user account created for the system, not for a person, holding only the permissions the integration needs. It signs in the same way staff do, receives a short-lived access token and a refresh token, and sends the access token on every call.

1. Get an integration account

The facility's administrator, or Elix on their behalf, creates the account and gives it a role. Ask for a role that holds only what your integration uses. For example, a system that reads patients and lab results needs patients.patients.list, patients.patients.get and investigations.lab.list, and nothing that writes.

You receive the account's email address and an initial password. If the account is flagged to change its password, sign in to the Elix web app once and set a new one before using it from your system.

2. Look up the account

Sign-in is two calls. The first exchanges the email for the account's id:

curl -X POST https://api.app.elix.ng/api/v1/auth/verify \
  -H 'Content-Type: application/json' \
  -d '{"email": "lab-bridge@example-hospital.ng", "userType": "EHR"}'

{
  "userId": "6f1c2a7e-3b9d-4c51-9a0e-2d4b8f7c1e93",
  "mustChangePassword": false,
  "requiresPasswordSetup": false,
  "userType": "EHR"
}

The userId does not change, so your system can store it and skip this call afterwards.

3. Sign in

curl -X POST https://api.app.elix.ng/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"identity": "6f1c2a7e-3b9d-4c51-9a0e-2d4b8f7c1e93", "credential": "<password>", "userType": "EHR"}'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "c0b6e0a4-...",
  "userType": "EHR",
  "mustChangePassword": false
}

A wrong password or unknown account answers 403 with the same message either way. Repeated failures lock sign-in for that account for a while and answer 429. Back off rather than retry in a loop.

4. Call the API

Send the access token as a bearer token:

curl https://api.app.elix.ng/api/v1/patients/base?search=adeyemi \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-org-id: <organisation id>' \
  -H 'x-facility-id: <facility id>'

Facility headers

Clinical data is held per organisation and facility. Name them on each call with x-org-id and x-facility-id. If you leave them out, Elix uses the defaults on the integration account's profile. An integration that serves several facilities of one tenant sends the headers for the facility each call is about.

Purpose of use

Routes that return identifiable patient data take a purposeOfUse query parameter: TREATMENT, PAYMENT, OPS or RESEARCH. Some require it and answer 400 without it; others default to OPS. Send the purpose that matches why your system is reading the record. It is recorded in the patient's access log, and a restricted record can be refused for one purpose and allowed for another.

5. Keep the session

Access tokens last about fifteen minutes. Before or when one expires, exchange the refresh token for a new pair:

curl -X POST https://api.app.elix.ng/api/v1/auth/refresh \
  -H 'Content-Type: application/json' \
  -d '{"refreshToken": "c0b6e0a4-..."}'

The answer holds a new access token and a new refresh token. Store the new refresh token and discard the old one: each refresh token can be exchanged once. If a response is lost and you present the old token again within about a minute, Elix returns the same replacement rather than refusing, so a single retry is safe.

When your system shuts down or rotates its secret, end the session with POST /api/v1/auth/logout and the access token.

Errors

Status	Meaning	What to do
401	Missing, expired or revoked access token	Refresh, then retry once. If refresh fails, sign in again.
403	The account lacks the permission, the module is not enabled for the facility, or the patient's privacy setting refuses this purpose	Do not retry. Check the role and the purpose of use.
404	Not found, or outside your tenant or facility	Check the id and the facility headers.
429	Too many failed sign-ins	Wait before signing in again.

Error bodies have the shape {"statusCode": 403, "message": "...", "error": "Forbidden"}.

Looking after the credential

• Keep the password and tokens in a secret store, never in source code or logs.
• Use one integration account per system, so access can be withdrawn from one without affecting another.
• Ask the facility to disable the account when the integration is retired.

Machine credentials

Server-to-server credentials using the OAuth 2.0 client credentials grant are planned for partner systems. Until they are available, integration accounts as described above are the supported way in. This page will be updated when that changes.