Security Model

Medipal processes health data, so security is part of the product design rather than an add-on. This page describes the model at the level administrators and integrators need. Deployment-specific hardening is covered in Deploying an Instance.

Authentication

Method	Who	Notes
Username and password	Clinicians, administrators	Password reset by email; administrators can require a password change
Single sign-on (Microsoft Entra / Azure AD)	Clinicians, administrators	Users sign in with their organisation account; roles can be mapped from directory groups
Multi-factor authentication	Clinicians, administrators	Time-based one-time codes from an authenticator app; can be enforced per user
Device pairing	Patients	Patients never use passwords; a device is paired once from the web app and can be revoked
API keys	External systems	Scoped, optionally expiring keys for integrations

Sessions are short-lived and renewed automatically while the user is active. Signing out ends the session on the server as well as in the app.

Authorisation

Every API call is checked on the server against the caller's scopes. Scopes are fine-grained (read, write, delete, manage and execute, per resource type), and users receive them through roles. The web app hides what a user cannot do, but the API is the authority: a hidden button is never the only protection.

Folders add a second layer. Permissions on a folder (owner, editor, viewer) apply to everything inside it, so access to a study or department can be granted in one place. See Users, Roles & Scopes.

API keys

API keys carry their own set of scopes, independent of any user, and can be given an expiry date. The key value is displayed once at creation and cannot be retrieved later. Keys can be revoked at any time, and every call made with a key is attributable to it. See API Keys.

Secrets and the vault

Credentials for external systems (SMTP servers, FHIR endpoints, third-party APIs) are stored in the vault, encrypted at rest. Configuration refers to a vault entry by name; the secret itself is resolved on the server at the moment it is needed and is never returned to the browser or written into logs. Vault entries can be rotated without changing the configuration that uses them. See Vault.

Data separation

Each organisation has its own instance with its own database. Requests are bound to the instance and tenant they were issued for, so data cannot cross organisations. Anonymous questionnaires store responses without any identifying information.

Patient devices and the mobile app

Pairing binds a device to a patient and an instance. The mobile app stores questionnaires and unsent answers in an encrypted local database and communicates only over HTTPS. A device can be revoked from the web app, after which it can no longer synchronise. See Patients & Devices and Mobile App.

Webhooks

Every webhook delivery is signed with a secret shared with the receiving system, so receivers can verify that a delivery is genuine and has not been altered. Deliveries are retried on failure and their status is visible in the web app. See Events & Webhooks.

Consent

Patients see the current consent documents before they take part, and their acceptance is recorded with the document version. See Consent Documents.

Recommendations for administrators

• Turn on multi-factor authentication for all staff accounts, or use single sign-on with your organisation's identity provider.
• Give users the least privilege that lets them work: prefer folder permissions over broad roles.
• Create one API key per integration, with only the scopes it needs and an expiry date, and rotate keys periodically.
• Keep every external credential in the vault; never paste secrets into configuration fields that accept plain text.
• Review roles, API keys and paired devices regularly and revoke what is no longer used.
• Keep the instance up to date; security fixes are delivered through regular releases.