Help Screens Sign-in & identity
Two-factor challenge AUTH-02
Complete sign-in with a TOTP code or a recovery code.
| Who can use it | Holder of mfa_token |
|---|---|
| Where it is | /sign-in/mfa · link: https://hub.substratalapps.com/sign-in/mfa or substratal://sign-in/mfa |
| Available on | Web (PWA), iOS / iPadOS, Android, Windows, Linux (GNOME), macOS |
| Phase | MVP |
Entering your code
Enter the 6-digit code from your authenticator app. The challenge is only valid for about five minutes; after that you start again from sign-in.
- Lost your phone? Choose Use a recovery code and enter one of the codes you saved when you turned two-factor on. Each one works once.
- Lost both? An administrator with
users.managecan reset your two-factor after confirming who you are. - Codes keep failing? Codes change every 30 seconds, so check that your phone sets its clock automatically.
What you can do here
- Verify — 200 → same as AUTH-01 success. 401 → "That code didn't work." clear field. Expired → back to AUTH-01 with message. 429 → countdown.
Related guides
- Signing in and keeping your account secure — Sign in, two-factor authentication, sessions and signing out everywhere.
- Using the Hub on macOS — Install the Mac app, sign in, get around with the keyboard, use several windows, and point it at a local API.
- Troubleshooting — What an error message means and what to do about it, from sign-in problems to update notices and API errors.
- Substratal on Windows — Install the Windows app, sign in, find your way around, keyboard shortcuts, notifications, and what's in each release.
- Substratal on Linux — Install and run the Hub on GNOME and other Linux desktops, how it signs in, how notifications arrive, and Linux-only tips.
- Set up the Windows app as an administrator — From a fresh install to a secured, signed-in admin workstation, with the shortcuts that make daily work fast.
On your platform
| App | Status | How it's built |
|---|---|---|
| Web (PWA) | — | Standalone route outside the app shell, centered card ≥ 768 px, full-bleed on phone |
| iOS / iPadOS | — | fullScreenCover |
| Android | Available in 0.1.0 | Route outside NavigationSuiteScaffold |
| Windows | — | Full-window page before the shell (no NavigationView) |
| Linux (GNOME) | — | Separate AdwWindow with AdwClamp |
| macOS | — | Separate Window scene (720×560, no sidebar) |
Status is reported by each app's repository; — means that app doesn't report it yet.
For developers: API calls
| Method | Path | What it does |
|---|---|---|
| POST | /auth/mfa/verify | Complete a login that returned an MFA challenge |
Every call sends Substratal-Version: 1. Paths are at the host root, with no /v1.