Two-factor authentication (MFA)
Two-factor authentication (MFA) protects your account with an extra layer on top of your password. Once enabled, every sign-in also requires a 6-digit code from an authenticator app. This documentation covers two screens: the setup screen (/mfa/setup), where you enable MFA, and the verification screen (/mfa/challenge), where you enter your code when signing in. Both screens are intended for practitioners who want to add extra protection to their own account.
Overview
| Route | /mfa/setup (set up), /mfa/challenge (verify when signing in) |
| Audience | Practitioner |
| Required permissions | No specific permission; any signed-in user can set up their own MFA |
Setting up happens in a few steps: you start the setup, scan the QR code with an authenticator app, confirm with a one-time code, and save your recovery codes. After that, the verification screen asks for a code on every new sign-in. If you no longer have access to your authenticator app, you can sign in with a recovery code.
You need an authenticator app, for example Google Authenticator, Authy, or Microsoft Authenticator.
How it works
MFA adds a second step to signing in: besides your password (something you know) you prove that you hold a pre-registered authenticator (something you have). The sections below explain the model behind the screens — which factors exist, how recovery codes behave, why enabling asks for extra confirmation, and how your organization's policy comes into play.
TOTP factors and methods
The factor is a TOTP (Time-based One-Time Password). During setup Scrivio shares a secret key with your authenticator app (via the QR code or the manual code). Your app combines that key with the current time to derive a new 6-digit code roughly every 30 seconds. The server computes the same code and compares them; nothing has to travel over the network, so it even works without internet on your phone.
You can register multiple methods side by side (for example your phone and a second device). One method is your preferred method and is requested by default. If you have set up more than one, the verification screen shows which methods are available, so you can pick another when your preferred device is not at hand.
Recovery codes
Recovery codes are your safety net for when you lose access to an authenticator app. When you enable MFA, Scrivio generates a finite set of codes once, which you can never view in full again afterwards (only their hashes are stored). Store them somewhere safe right away.
| Property | Behaviour |
|---|---|
| One-time | Each recovery code works exactly once; it is spent after use. |
| Finite | The set is limited — use many and you can run out. |
| Regenerating | Generating a new set invalidates the old set at once, including codes you had not used yet. |
You can watch your stock decrease: the system tracks how many unused codes you have left. When it runs low, generate a new set — and replace your old list, because it stops working from that moment on.
Secure re-authentication when enabling
Enabling MFA is a sensitive action, so it requires step-up re-authentication: your session must have been confirmed recently. If you signed in too long ago, the setup screen first asks you to sign in again; the setup then resumes automatically. This stops someone who briefly takes over your screen from changing your second factor. In addition, your email address must be verified before you can enable MFA.
Organization policy and transition period
An organization administrator can make MFA required for the whole organization. To avoid locking everyone out at once, a transition period (grace period) applies:
- From the moment MFA becomes required, a preset number of days runs during which enabling is still optional. In that window you can keep working and pick a convenient moment to set MFA up.
- If you already enabled MFA, the policy does not affect you — you already comply.
- Once the transition period has expired and you still have no MFA, you must enable it before you can continue. Administrators see in their overview who is still without MFA and whose transition period has lapsed.
As long as your organization does not require MFA, setting it up stays entirely voluntary.
Enable MFA
Open the setup screen at /mfa/setup. The screen opens with a short explanation and a Start setup button. Click it to begin.
If you signed in too long ago, the screen first asks you to sign in again before continuing. This is a security measure: after re-confirming your password, the setup resumes automatically.
After starting, you continue with scanning the QR code. To stop, click Cancel to return to your profile.
Scan the QR code
After starting, the screen shows a QR code. Open your authenticator app and scan the code to add your account. If you cannot scan the code, use the displayed manual code (the secret key) and enter it in your app.
Click Next to verify the key you just added. Enter the 6-digit code that your authenticator app shows and click Confirm. If the code is incorrect, a message appears; check the code and try again. Use Back to view the QR code again.
| Field | Required | Description |
|---|---|---|
| Verification code | Yes | The 6-digit code from your authenticator app. The code is checked automatically once all six digits are entered. |
If the code is valid, the screen shows your recovery codes. Store these codes in a safe place: they give you access to your account if you lose access to your authenticator app. Click I have saved my codes to confirm. MFA is now enabled and every following sign-in requires your authenticator app.
Complete sign-in verification
Once MFA is enabled, the verification screen (/mfa/challenge) appears when you sign in. Enter the 6-digit code from your authenticator app here. The code is checked automatically once you have entered all six digits; you can also click Verify. If the code is incorrect, a message appears and the field is cleared so you can try again. After a successful verification you continue to the page you were heading to, or to your dashboard.
If you have set up multiple methods, the screen shows which methods are available.
No access to your authenticator? Click Use a recovery code. Enter one of the recovery codes you saved during setup and click Verify. Note: a recovery code can only be used once. The Back to verification button returns you to entering an authenticator code.
| Field | Required | Description |
|---|---|---|
| Verification code | Yes | The 6-digit code from your authenticator app. |
| Recovery code | No | One of your saved recovery codes; only needed if you have no access to your authenticator app. |
Use Cancel to abort the verification and return to the sign-in screen.
Return to profile
Setting up MFA always starts from your profile. If you click Cancel during setup, or finish the setup with Done, you return to your profile page. From your profile you manage your account settings and can review your two-factor authentication later.