Help Screens Sign-in & identity
Sign in AUTH-01
Exchange email + password for a session, or start an MFA challenge.
| Who can use it | Unauthenticated |
|---|---|
| Where it is | /sign-in · link: https://hub.substratalapps.com/sign-in or substratal://sign-in |
| Available on | Web (PWA), iOS / iPadOS, Android, Windows, Linux (GNOME), macOS |
| Phase | MVP |
Signing in
Enter the email and password for your Substratal account and choose Sign in. Your password manager can fill both fields, and the eye button shows or hides the password. If your account has two-factor authentication, you're asked for a code next (Two-factor challenge).
| You see | What to do |
|---|---|
| That email and password don't match. | Check both. For security, the message never says which one is wrong, or whether the account exists. |
| Too many attempts. | After 5 failed attempts in 15 minutes, sign-in is locked for 15 minutes. Wait, then try again. |
| This account is suspended. | An administrator suspended it. Contact them. |
| This version of the app is no longer supported. | Update the app. The API version it uses has been retired. |
| You're offline. | Connect, then try again. |
What you can do here
- Sign in — 200 AuthSession → store tokens → go to
nextor APP-01. 200 MfaChallenge → AUTH-02 with mfa_token. - — — 401 → inline form error "Email or password is incorrect." (never reveal which). 403 → account suspended/locked message;
test_user_expired→ "This test account has expired." 429 → disable button, countdown from Retry-After.
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.
- The Android app — Installing the Android Hub, how it lays out on phones, tablets and Chromebooks, links, offline use and security.
- 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/login | Exchange email and password for a session (or an MFA challenge) |
| POST | /auth/sso/{provider}/callback | Complete an SSO login (reserved — 501 until the broker integration ships) |
Every call sends Substratal-Version: 1. Paths are at the host root, with no /v1.