Launch app APP-03
Mint an app token (or authorization code) and open the app.
| Who can use it | Active entitlement |
|---|---|
| Where it is | /apps/:appId/launch · link: https://hub.substratalapps.com/apps/:appId/launch or substratal://apps/:appId/launch |
| Available on | Web (PWA), iOS / iPadOS, Android, Windows, Linux (GNOME), macOS |
| Phase | MVP |
What you can do here
- Embedded launch — 200 AppToken (5-min JWT) → open launch_url with token per app contract; never cache the token. 403 → refresh status, show APP-02;
embedded_login_not_allowed(a third-party, self-registered app) → hosted launch below, or openlaunch_urlwithout a token whilehosted_launchis off. 409 → choose org. - Hosted launch (Phase 3) — 201 → open redirect_uri?code=…&state=… in system browser / auth session
Related guides
- Home and your apps — See the apps you have access to, open them, and find apps you used to have.
- Register an application and launch it from the Hub — From an empty catalog entry to people opening your app from Home.
On your platform
| App | Status | How it's built |
|---|---|---|
| Web (PWA) | — | window.open (new tab) / same-tab redirect for PKCE |
| iOS / iPadOS | — | openURL / ASWebAuthenticationSession |
| Android | Planned | Custom Tabs / Auth Tab |
| Windows | — | Launcher.LaunchUriAsync |
| Linux (GNOME) | — | GtkUriLauncher (OpenURI portal) |
| macOS | — | NSWorkspace.open / ASWebAuthenticationSession |
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/app-tokens | Mint a per-app JWT from a platform session (embedded login) |
| POST | /auth/oauth/authorization-codes | Mint a one-time authorization code for a hosted launch (PKCE) |
Every call sends Substratal-Version: 1. Paths are at the host root, with no /v1.