OpenMax
Free Trial

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}. id is {slug}-{4 random characters} generated at first publish (slug comes from the manifest; the 4 characters are lowercase letters + digits, excluding 0 / o / 1 / l / i), such as leantime-k7mp. It is globally unique, never changes after first publish, and is only used for locating the app; it does not imply permissions.
  • How it opens: after checking the installation status and the entry's roles, the shell opens {url}{sub-path} directly. If open includes embed, 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-ancestors to allow Workspace, and remove X-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 (Lax is 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 honor Partitioned. 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 Partitioned are 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 carry rel="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 url itself 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 post openmax:theme:request / openmax:lang:request to window.parent to have the host send them again. Messages go only to the origin of the manifest url, so url must 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:

  • url with 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 of url.
  • Apps whose routing is trailing-slash sensitive (/dashboard differs from /dashboard/): write the entry path without 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 use https://example.com/leantime/auth/openmax/callback. Its host must match url; 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 (/callback and /callback/ are two different URLs). For other host restrictions see "Validation rules" in App types and manifest.

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-sdk this is openChat({ memberId }). The package is not yet published to npm, so send the postMessage yourself using the message format above.
  • https://openmax.com in 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