Authentication & Authorization

Two separate questions are answered for every request: who is calling (authentication) and what they may do (authorization). This page explains both mechanisms at the level needed to integrate with or operate an instance. Administrator how-tos are in Users, Roles & Scopes and API Keys.

Authentication

Method	Who uses it	How it works
Credentials	Users of the web app	Email and password are exchanged for a short-lived access token and a longer-lived refresh token. Passwords are stored as salted hashes.
Multi-factor (TOTP)	Users with MFA enabled	After a correct password the server issues a challenge token that can do only one thing: answer the MFA challenge. A full session is issued only after a valid authenticator code.
Microsoft Entra ID	Organisations with Microsoft 365	The web app runs the Microsoft sign-in flow and hands the resulting token to the API once. The server verifies its signature against the tenant's published keys, checks that it was issued by the configured tenant for this application, matches the identity to a local user, and then issues its own tokens. No account is created by sign-in alone.
Device authentication	The mobile app	A patient's device is paired through an invitation issued by a clinician. The device receives its own tokens, scoped to that patient and instance, and refreshes them silently.
API keys	Integrations and plugins	Long-lived credentials created by an administrator with a role, an optional scope subset and an optional expiry. They are sent either as a bearer token or in a dedicated header and act on behalf of their creator's role.

Sessions are represented by the access token; refresh tokens are stored server-side so that an administrator can revoke a user's sessions, and signing out invalidates the refresh token. An account can be disabled, which ends its ability to authenticate by any method while keeping its history. Users can be required to change their password at next sign-in.

Directory synchronisation

When Microsoft Entra ID is configured, an instance can go beyond sign-in and keep accounts aligned with the organisation's directory:

• Provisioning. Users who match a mapping rule are created on first contact and bound to their immutable directory identity, so a renamed mailbox does not create a second account.
• Role mapping. A mapping defines which directory groups grant which Medipal roles. Desired roles are recomputed on every run, so correcting the mapping heals every affected user.
• Sources. Group membership can be read from the sign-in token and from a periodic directory sweep run by the scheduler.
• Safety. Synchronisation only manages accounts and roles it created itself; roles granted by an administrator are never removed by it. A partial or failed directory read never revokes anything. Users disabled in the directory are disabled locally and keep their roles, so returning staff regain access with a single status change. Each stage can be run in a dry-run mode that only reports what would change.

The mapping is part of the instance configuration; see Configuration & Vault.

Authorization

Authorization has two layers that are combined for every request.

Roles and scopes

A scope is a permission on one resource family for one action: read, write, delete, manage or execute. Resource families cover questionnaires, folders, patients, enrollments, submissions, users, roles, permissions, devices, vault, plugins, workflows, webhooks, event subscriptions, consent, clinical sources, analytics, AI and authentication itself.

A role is a named set of scopes. Three roles are built in:

Role	Intent
admin	Everything.
provider	Clinical work: questionnaires, patients, enrollments, results, without instance administration.
integration	Machine access for API keys and plugins: broad data access, no user or security administration.

Custom roles can be composed from any set of scopes. Every endpoint declares the scopes it accepts; the caller passes if any of its roles grants one of them. API keys inherit their creator's role and may be narrowed to a subset of its scopes.

Content permissions

Scopes say what kind of thing a caller may touch; permissions say which specific content. Folders and questionnaires carry permissions with three access levels (owner, editor, viewer), and folder permissions can apply recursively down the tree. A caller's effective access to an item is the most permissive grant found on the item or on any ancestor with a recursive permission. See Folders & Configuration.

How the layers combine

1. The endpoint's scope check runs first. A user without questionnaire:write cannot edit any questionnaire, whatever permissions they hold.
2. The service then resolves content permissions. A user with questionnaire:write still cannot edit a questionnaire in a folder they cannot see.
3. Administrators are subject to the same checks; the admin role simply grants every scope and owner access.

What integrators should take from this

• Request the narrowest role and scope subset your integration needs, and set an expiry on API keys.
• Expect 401 when the credential itself is not accepted and 403 when it is accepted but insufficient; do not retry either.
• Treat the identity provider as a sign-in mechanism only; roles are always managed in Medipal or through the directory mapping.