Two-step sign-in

Two-step sign-in means a password is not enough. The person also types a 6-digit code from an authenticator app on their phone. The code is a TOTP (time-based one-time password, the standard RFC 6238): it changes every 30 seconds, and one step of clock drift is allowed.

It is mandatory for every platform operator. Until a session has passed the second step, every /api/platform/* call answers 403 second_factor_required, or 403 second_factor_enrolment_required if the operator has not set it up yet. For company users it is optional, using the same endpoints.

Do this: set it up

1. Sign in at the normal sign-in page with e-mail and password. You land on /platform.
2. Until the second step is done, the console shows only a gate in place of the page. A new operator sees Set up two-step sign-in to continue. This is the same card as on Your account.
3. Press Set up two-step sign-in. A QR code and the secret appear, with 10 recovery codes. They are shown once.
4. Scan the QR code with an authenticator app (or type the secret). Save the recovery codes somewhere safe, offline.
5. Type the current 6-digit code to confirm. This proves the app works and turns it on.

Behind the screen: POST /api/auth/2fa/enrol (returns an otpauth_uri, a secret_base32 and the codes), then POST /api/auth/2fa/confirm.

Do this: each sign-in

1. Sign in with e-mail and password.
2. The gate shows Enter your sign-in code. Type the six digits from the app.

Until that succeeds, only /api/auth/* works (POST /api/auth/2fa/verify).

Recovery codes

If the phone is lost, press I lost my phone. Use a recovery code on the gate and type one instead. Each recovery code works once. They are stored only as hashes, so nobody can read them back.

Rules that protect it

• A code cannot be used twice, even within its 30 seconds.
• Wrong codes are counted per person. Five failures lock them for 60 seconds, doubling each time up to one hour. You get 429 with Retry-After. During a lock even the right code waits.
• The secret is stored encrypted.
• An operator cannot turn it off. A company user can, with their password and a code (POST /api/auth/2fa/disable).

Lost phone and no codes

A platform owner resets it: Operators, the operator’s menu, Reset two-step (POST /operators/{id}/reset-2fa). For a company user, use People (or the company’s People tab), Reset two-step sign-in with a reason (POST /users/{id}/reset-2fa); platform_support may do that too. The person then sets it up again from step 1.

The local demo bypass

PLATFORM_2FA_DEV_BYPASS=1 lets operators in without the second step. It exists only for local demos. The gateway logs it at error level when it starts and at every operator sign-in, and refuses to start if APP_ENV=production and it is set. Never set it on a real system.