Two-factor authentication

Turning it on

1. 1

   Start the setup

   POST /v1/oauth/mfa/setup { appId, email } → { secretKey, qrCodeUri }. Show qrCodeUri as a QR code, and secretKey for typing in by hand. Nothing is saved yet.

2. 2

   Confirm with a code

   The user scans it and types the current code: POST /v1/oauth/mfa/verify-setup { appId, email, base32Secret: secretKey, verificationCode } → 204. Two-factor authentication is now on, and the secret is stored encrypted.

Signing in with it

login answers 202 { requiresMfa: true, mfaToken }, and a Google sign-in puts ?mfaToken=… on your callback URL instead of a connection token. The mfaToken is valid for 5 minutes and 5 attempts. Ask the user for their code, then:

POST /v1/oauth/verify-mfa { appId, mfaToken, mfaCode } → tokens. A wrong code answers 400 Mfa.InvalidCode, and so does a code that has already signed the user in, or an older one: each code signs in once, so ask for the next.

Turning it off

POST /v1/oauth/mfa/disable { appId, email, password }, with the user's current password.