System states GLB-03
App-wide banners and blocking states.
| Who can use it | — |
|---|---|
| Where it is | Appears on any screen when the situation calls for it. |
| Available on | Web (PWA), iOS / iPadOS, Android, Windows, Linux (GNOME), macOS |
| Phase | MVP |
What you can do here
- Silent token refresh — single-flight; rotate refresh token atomically (CLIENT-ARCHITECTURE §2)
- Connectivity probe — used after offline/503 to decide when to clear the banner (exempt from
Substratal-Version) - Forced sign-out — on session_revoked or user request; the server deactivates this session's push devices
- Badge refresh — on launch, foreground, after a push arrives, and every 60 s while visible (Windows/Linux: also in background) → app icon/Dock/taskbar/PWA badge
Related guides
- Getting started with Substratal Hub — What the Hub is, how it's organized, and where to find things on each platform.
- 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.
On your platform
| App | Status | How it's built |
|---|---|---|
| Web (PWA) | — | Top-layer <dialog> / popover |
| iOS / iPadOS | — | Sheet or search tab |
| Android | Planned | Expanded SearchBar / sheet |
| Windows | — | Title-bar flyout / pane |
| Linux (GNOME) | — | Popover / overlay |
| macOS | — | Floating panel / toolbar popover |
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 |
|---|---|---|
| GET | /health | Health check |
| POST | /auth/token/refresh | Rotate a platform refresh token for a new access token |
| POST | /auth/logout | Revoke the current session, or every session |
| GET | /users/{id}/notifications/unread-count | Count unread notifications, in total and per Application (self or the app's own key) |
Every call sends Substratal-Version: 1. Paths are at the host root, with no /v1.