Open modes and URLs
How the Workspace shell opens your app, how platform links map to app URLs, display parameters on the entry URL, route sync, and app requests to open a conversation (navigate).
Open modes and URLs
This page covers how the Workspace shell opens your app: how platform links map to app URLs, what you need to do for embedding (iframe), which parameters and messages the shell sends, and how your app syncs its current page to the shell and requests to open a conversation.
URL rules and open modes
- URL rules:
- Official / global apps:
/workspace/apps/{slug}(such as/workspace/apps/pages). - Organization apps:
/workspace/apps/custom/{id}.idis{slug}-{4 random characters}generated at first publish (slug comes from the manifest; the 4 characters are lowercase letters + digits, excluding0/o/1/l/i), such asleantime-k7mp. It is globally unique, never changes after first publish, and is only used for locating the app; it does not imply permissions.
- Official / global apps:
- How it opens: after checking the installation status and the entry's
roles, the shell opens{url}{sub-path}directly. Ifopenincludesembed, it goes into an in-page iframe; otherwise the shell shows an "Open in new tab" link. The shell does not issue codes or pass identity; your in-app route is the sub-path. Two display parameters are added to the URL when opening (see "Parameters on the entry URL"). - How the sub-path is chosen: for a platform link
/workspace/apps/…/{sub-path}, the entry is chosen by "exact match → the longest visible entry it falls under (/catches every deep link)"; if nothing matches, it falls back to the first visible entry (preferring/). In that case the fallback entry itself is opened, so URLs the user cannot see are never passed to the app. - When embed fails to open: the top bar always has "Blank page?" (same as opening in a new tab), and if nothing loads in 10 seconds the shell suggests opening in a new tab.
To support embed, your app needs
CSP: set
frame-ancestorsto allow Workspace, and removeX-Frame-Options: DENY.Workspace origin (frame-ancestors / issuer):
https://openmax.com.cookies: inside the iframe your cookies are third-party cookies. Both sign-in flow cookies and session cookies need
Secure; HttpOnly; SameSite=None; Partitioned(Laxis fine when opened at top level). Safari and every browser on iPhone / iPad (WebKit) do not store or send these cookies at all, and only Chromium-based browsers honorPartitioned. So when embedded, use the host-issued authorization code from Sign-in ("Sign-in when embedded") instead: do not rely on cookies for sign-in, and do not redirect inside the iframe.Sessions are not shared: cookies with
Partitionedare partitioned by top-level site. A session created in the iframe is not shared with a session in a new tab (top level); the first new-tab open goes through (silent) authorization again, which is expected. After you integrate Sign-in ("Sign-in when embedded"), the iframe session lives in a request header and is likewise not shared with the new tab.iframe attributes:
sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads",referrerPolicy="no-referrer",allow="clipboard-write"(the app gets no Referer and cannot navigate the top-level page). New-tab links carryrel="noopener noreferrer".
Parameters on the entry URL (display only)
Every time the shell hands out a URL (iframe src, top bar / "Blank page?" / 10-second hint / "Open in new tab" link, direct new-tab link on app catalog cards), it sets these on the query:
| Parameter | Values | Meaning |
|---|---|---|
theme |
light / dark |
Workspace's resolved theme ("Follow system" is already resolved from the system preference) |
openmax_lang |
en / zh |
Current UI language (en when unrecognized) |
- Only these two: the shell does not pass code, token, org_id, member_id, or any identity information; query parameters the user added to the platform link are not passed through either.
- Display only, never for authentication: anyone can edit the address bar, so never use them to decide "opened from OpenMax", pick an organization / tenant, skip sign-in, or decide permissions. Identity comes only from the authorization result of sign-in.
- Same-name parameters are overwritten: query parameters in
urlitself are not carried into the entry URL (only the path is joined). Your app's routing / sign-in middleware must tolerate these two unknown parameters (do not return 400 or drop the session because of them). - Frozen per open in the iframe: later theme / language changes by the user do not change src (the app is not reloaded); instead the shell posts
{type:"openmax:theme", mode}/{type:"openmax:lang", lang}(each is also sent once on every iframe load). The app can postopenmax:theme:request/openmax:lang:requesttowindow.parentto have the host send them again. Messages go only to the origin of the manifesturl, sourlmust be your final origin (no further 30x to another domain). New-tab links always carry the current values. - Lost after an authorization redirect: when your app redirects to authorization and comes back, these two parameters are lost. Save them in your session / local storage first, or ask again with the request messages above after returning.
The protocol is wrapped by @openmaxai/app-sdk. This package is not yet published to npm (experimental 0.0.0 version), so you can implement it yourself: two query parameters + four theme / language messages; route sync adds one more (see "Route sync"), requesting to open a conversation adds three (see "App requests to open a conversation"), and embedded sign-in adds three (see Sign-in ("Sign-in when embedded")).
URL composition examples
Joining rules:
urlwith its trailing slash removed +/+ each sub-path segment (empty segments ignored).- When the sub-path is
/, you get the url path itself plus one/. - The sub-path's trailing slash is not kept.
- If the sub-path contains
./..segments, backslashes, control characters, or decoded?/#, it is not opened (the shell reports it as unavailable).
In the table below, … stands for ?theme=light&openmax_lang=zh:
| manifest url | Platform link the user opens | What the shell actually opens |
|---|---|---|
https://pm.example.com/ |
/workspace/apps/custom/leantime-k7mp |
https://pm.example.com/… |
https://pm.example.com/ |
…/custom/leantime-k7mp/projects/12 |
https://pm.example.com/projects/12… |
https://example.com/leantime (no trailing slash) |
…/custom/leantime-k7mp |
https://example.com/leantime/… |
https://example.com/leantime/ |
…/custom/leantime-k7mp/dashboard/ |
https://example.com/leantime/dashboard… (trailing slash removed) |
https://example.com/leantime/?tenant=a |
…/custom/leantime-k7mp |
https://example.com/leantime/… (tenant=a not carried) |
- Prefix deployments (the app is mounted under a reverse-proxy sub-path, such as
/leantime): links, redirects, static assets, and cookie Path generated by the app must all include this prefix (for example, configure the app's external base URL). Otherwise the page the shell opens will load, but the first redirect will drop the prefix. The shell only guarantees that the URL it opens falls under the path ofurl. - Apps whose routing is trailing-slash sensitive (
/dashboarddiffers from/dashboard/): write the entrypathwithout a trailing slash, and make the app accept it. - redirect_uri is a separate item, not affected by the joining rules above, and does not need to be an entry. For example, with
url = https://example.com/leantime/you can usehttps://example.com/leantime/auth/openmax/callback. Its host must matchurl; the value in the authorization request, the value in the token request, and the value in the manifest must all be byte-for-byte identical (/callbackand/callback/are two different URLs). For other host restrictions see "Validation rules" in App types and manifest.
Route sync (optional, recommended for embedded apps)
Status: Live.
What it solves: an embedded app runs in a cross-origin iframe, so the shell cannot see which page you navigated to inside it. Without it, when a user goes to some page in the app and refreshes the browser, the shell reopens the platform link in the address bar (the one from entry), and the iframe goes back to the entry page; copying the address bar also only gives the entry. With it, the shell URL follows the app: refresh stays on the same page, the address bar is the link to the current page, and a colleague you share it with can open the same page (they re-select an entry by their own role; if they cannot see it, it falls back with a notice, with no privilege escalation).
How to integrate: on every page change (including the first screen), post a message to the parent window, only to the Workspace origin https://openmax.com, never "*":
parent.postMessage({ type: "openmax:location", path: location.pathname }, "https://openmax.com");
With @openmaxai/app-sdk this is equivalent to connectWorkspace({ workspaceOrigin }).reportRoute() (defaults to location.pathname; does not send when not embedded, same as last time, or the path is invalid). The SDK is not yet published to npm, so you can use the single line above directly.
| Item | Rule |
|---|---|
| path | Your document's current location.pathname, including your own deployment prefix (when the manifest url is https://example.com/leantime/, send /leantime/projects/12); the shell strips the prefix. You do not need to know what your platform link looks like |
| Format | Starts with a single / (//, /\, and anything with a scheme are rejected), ≤ 2048 characters, no ?, #, backslashes, control characters, or encoded / \ . (%2F %5C %2E), and no . / .. segments |
| Reversible | Must fall under the path of the manifest url, and joining it back with the rules in "URL composition examples" must give this page (trailing slash ignored); paths that cannot be joined back, such as empty segments (/a//b), are rejected |
| Visible | Must fall under an entry visible to the current user (no fallback when choosing the entry as in "URL rules and open modes"); anything that does not fit is rejected, since writing it into the URL would only create a link that "falls back as soon as it opens" |
| Path only | query and hash are not synced: the shell never passes query through when opening, so refresh can only restore down to the path. Apps that use ?id= to tell detail pages apart will go back to the list page on refresh; to restore the detail page, put the id in the path (/items/42) |
| Source | The shell only accepts messages from your iframe (event.source) whose event.origin equals the origin of the manifest url, so url must be your final origin |
- If any rule is not met, the shell silently ignores the message and the URL stays on the last accepted page; no error message is returned. The shell does not send an ack either.
- The shell only changes its own URL with
history.replaceState: no navigation, no reload of your iframe, no new history entry. Your pushState is already in the browser's session history; when the user presses Back, your router goes back and reports the current page again (the "send on every page change" in the recipes below covers this naturally), and the shell URL follows. - The shell never drives your navigation in the other direction: on refresh / share the shell opens
{url}{sub-path}directly per "URL rules and open modes", so your app must be able to start directly on a deep page (deep-link routing and server-rendered pages already can). - Entry dropdown in the top bar: once the URL has followed to
/reports/42, selecting "Reports" again makes the shell reopen the entry page (iframe reload); if you reported that you are on an entry page, selecting that entry again does not reload. - If the shell rejected your most recent report (a page outside visible entries, a sign-in callback page, invalid shape, etc.), it treats the location as unknown: selecting the current entry again reopens the entry page.
- If several messages are sent in the same frame, the shell only handles the last one; the same value is not rewritten.
Do not report these pages: OAuth callback (redirect_uri), sign-in relays, one-time confirmation pages, submission-success pages, and other routes that cannot be replayed after a refresh. A refresh replays the callback without query, and the app errors. The shell does not know your redirect_uri, so it cannot block these for you; you must exclude them yourself. The only exception: reports whose written-back platform link contains
/auth/callback(as-is or decoded, such as/auth/callback,/reports/auth/callback) are ignored by the shell, because Workspace would treat them as its own sign-in callback page and stop renewal. Do not rely on this; still exclude callback pages yourself.
Framework recipes (all use location.pathname, so the router's basename / base / basePath is included naturally):
// Shared part
const workspace = connectWorkspace({ workspaceOrigin: WORKSPACE_ORIGIN });
const skip = (p) => p.startsWith("/auth/"); // Callbacks, sign-in relays, and other one-time routes
// React Router
const { pathname } = useLocation();
useEffect(() => { if (!skip(pathname)) workspace.reportRoute(); }, [pathname]);
// Vue Router
router.afterEach((to) => { if (!skip(to.path)) workspace.reportRoute(); });
// Next.js (App Router, client component)
const pathname = usePathname();
useEffect(() => { if (!skip(pathname)) workspace.reportRoute(); }, [pathname]);
// Server-rendered pages (one document per page): send once on page load
if (!skip(location.pathname)) workspace.reportRoute();
If you do not integrate: behavior is unchanged (refresh returns to the current entry page). The shell has no fallback that works without the app: a cross-origin iframe's URL is protected by the same-origin policy, and the parent page sees no events for in-SPA navigation. If you do not want to integrate but still want refresh to keep the page, the app must record the current page in sessionStorage and restore it on startup; that is the app's own implementation and the platform makes no promise about it.
App requests to open a conversation (navigate)
Status: Coming soon.
An embedded app can ask the host to open a conversation: a direct message with a member, or an existing conversation. For example, a "Chat with owner" button on a task detail page.
Request: the app posts openmax:navigate:request to the parent window, only to the Workspace origin:
// Open a direct message with a member
parent.postMessage({
type: "openmax:navigate:request",
requestId: "req_01",
target: { kind: "dm", memberId: "MEMBER_ID" }
}, "https://openmax.com");
// Open a conversation
parent.postMessage({
type: "openmax:navigate:request",
requestId: "req_02",
target: { kind: "conversation", conversationId: "CONVERSATION_ID" }
}, "https://openmax.com");
Reply: the host replies with openmax:navigate:accepted or openmax:navigate:error. accepted only means the host received the request; it does not guarantee the conversation was opened.
window.addEventListener("message", (event) => {
if (event.source !== window.parent || event.origin !== "https://openmax.com") return;
const { type } = event.data || {};
if (type === "openmax:navigate:accepted") { /* Host received the request; does not mean the conversation is open */ }
if (type === "openmax:navigate:error") { /* Request failed; handle it per the error code table below */ }
});
| Item | Rule |
|---|---|
target |
Either {kind: "dm", memberId} or {kind: "conversation", conversationId} |
| id format | requestId, memberId, and conversationId must each be 1–64 characters of [A-Za-z0-9_-] |
| When to call | Must be called inside a user click (triggered by user action), never sent automatically on page load or from a timer |
| Rate limit | At most 10 per iframe per 60 seconds; rejected requests do not count; counted separately from authorization requests (Sign-in ("Sign-in when embedded")) |
| Context | Currently only opens the conversation; no context can be attached |
- In
@openmaxai/app-sdkthis isopenChat({ memberId }). The package is not yet published to npm, so send the postMessage yourself using the message format above. https://openmax.comin the code above is the Workspace origin.
Error codes: openmax:navigate:error carries an error code; with rate_limited it may also carry retryAfter (in seconds). Treat unknown codes as failed.
| Error code | Decided by | Meaning | What the app should do |
|---|---|---|---|
invalid_request |
Host | Malformed request (target is neither of the two kinds, or an id has the wrong format) |
Fix the code (development-time error) |
unsupported_target |
Host | The host does not support this target |
Fall back to the app's own approach (for example, tell the user to find the conversation in OpenMax); do not retry |
activation_required |
Host | Not triggered by a user click | Send it from a click handler instead; do not retry automatically |
rate_limited |
Host | Too frequent (see "Rate limit" in the table above); may carry retryAfter |
Tell the user to try again later; if retryAfter is present, do not send again before it |
failed |
Host | Other failures (including unrecognized codes) | Show the user a notice |
