MFA (TOTP)
Asiri supports time-based one-time passwords (TOTP) as a second factor on every account that signs in with email and password. Workspace admins and users with sensitive roles should always enrol; admin-only surfaces (apps/admin) can be enforced to require it.
TOTP codes are 6 digits, rotate every 30 seconds, and work with any standard authenticator app — 1Password, Bitwarden, Google Authenticator, Authy, the iCloud Keychain, and so on.
Enrolment
Enrolment is a three-step flow from Settings → Profile → Two-factor authentication.
1. Begin enrolment
Click Enable two-factor authentication. Asiri re-prompts for your current password — this is a re-auth check; an attacker who has hijacked your session shouldn’t be able to silently bind a factor they control.
The dashboard calls POST /v1/me/mfa/totp/enroll with your password and receives:
- A
totpURI— theotpauth://totp/...URI your authenticator app reads to provision a key. - A set of backup codes (single-use recovery codes).
2. Scan the QR code
The dashboard renders the totpURI as a QR code. Scan it with your authenticator app.
If you can’t scan, click Show key and type the secret in manually.
Your authenticator will start generating 6-digit codes that change every 30 seconds.
3. Verify
Enter the current code from your app and click Verify. Asiri calls
POST /v1/me/mfa/totp/verify to confirm the secret was provisioned correctly. Only
after a successful verification is MFA actually enabled on your account.
If the code is rejected, check that your device clock is in sync with network time — TOTP relies on both sides agreeing on the current 30-second window.
Backup codes
When you enable MFA, Asiri shows you a set of backup codes. Store them somewhere secure before leaving the page — they are shown once and never again. Each code can be used in place of a TOTP code exactly once.
Use a backup code when you don’t have your authenticator app: a lost phone, a new device that hasn’t synced yet, a flight without your usual hardware.
To rotate backup codes (recommended after using one), disable and re-enable MFA — a fresh set is generated on each enrolment.
Signing in with MFA
After your password authenticates, Asiri prompts for a 6-digit code. Enter the current code from your authenticator, or one of your remaining backup codes if you can’t reach the app. The session cookie issued at sign-in is bound to the MFA challenge — you won’t be prompted again until the session expires.
Recovery
If you lose both your authenticator and your backup codes, contact your workspace admin. They cannot see your codes (we don’t have them either), but an admin can revoke your sessions and reset the second factor on your account so you can re-enrol.
For accounts that are the sole admin of a workspace, contact Asiri support — recovery requires manual identity verification.
Disabling MFA
To turn MFA off, go to Settings → Profile → Two-factor authentication → Disable and
confirm with your password. Asiri calls DELETE /v1/me/mfa/totp; the action is recorded
in your workspace’s audit log.
Disabling MFA is the right move when you’re rotating to a new authenticator or removing a compromised factor. It is not the right move as a long-term posture — re-enrol immediately after the rotation.
Status check
GET /v1/me/mfa returns the current state for the signed-in user:
{
"enabled": true,
"methods": ["totp", "backup_code"],
"backupCodesRemaining": 8
}The dashboard uses this to drive the MFA status pill on the profile page.