OpenMax
Free Trial

Release and versions

How to ship a new version, migrate from the old launch flow, release practices and the pre-launch self-check.

Release and versions

Publishing new versions

  • The manifest version only accepts three numeric parts X.Y.Z (such as 1.0.0, 1.2.10). Versions with a suffix like 1.0.0-beta are rejected.
  • Each submitted version must be greater than existing versions. slug cannot change in a new version.
  • Every new version submitted by a member who is not an admin, or by an Agent, needs one admin's approval; an admin's own submission (a person with app management permission) is approved automatically. Whether approval is needed depends only on who submits, not on scope changes; when new scopes are added, the approval request highlights them. Until approval, the app keeps running on the old version.
  • Once new scopes are approved, members get them automatically on the app's next authorization, with no confirmation prompt.
  • redirect_uri follows the installed version; if you change it, switch your code only after the new version is installed.

For other manifest validation rules, see "Validation rules" in App types and manifest.

Migrating from the old launch flow

The old flow was: the shell called launch to issue a code, opened your redirect_uri with ?code=&state=, and the first open showed a "requested new permissions" consent dialog. This flow has been removed with no compatibility: the launch-app / consent-app APIs are gone, and the shell no longer sends you a code.

Three changes are needed:

  1. Add a "start authorization" entry point: when the app sees no session, it generates state, nonce and code_verifier, stores them server-side, and redirects to {issuer}/api/v1/apps/authorize (parameters in "Authorization request parameters" in Sign-in). Drop the assumption that "the shell opens the callback with a code". The shell now opens your url + sub-path, with only the display params theme / openmax_lang on the query (see "Parameters on the entry URL" in Open modes and URLs): no code / state, and no identity parameters.
  2. Have the callback check your own state and iss, and exchange the token with code_verifier: you generate state (previously the shell generated it and put a JSON path in it); store the return path in your server-side flow instead. Token requests without code_verifier are rejected (invalid_request). We suggest getting identity from the id_token + nonce, and using member_id as the user identifier.
  3. Embedding and error handling: when embedded, have the host issue the authorization code for you (see Sign-in ("Sign-in when embedded")); do not redirect inside the iframe and do not rely on cookies. Any cookies you still use should be SameSite=None; Secure; Partitioned, and set frame-ancestors to the Workspace origin of the right environment. Handle login_required / access_denied and add a loop-guard marker. Remove all logic that relies on the "first-open consent dialog" (there is no per-member consent now).

Release practices

Platform requirements: "Validation rules", "Publishing new versions" above, "Visibility and approval", and "Launch checklist". The manifest version accepts only X.Y.Z, and each one must be greater than the previous one. Below is how the reference implementation (OpenMax Workflows) does it. These are recommendations, not platform requirements.

  • Keep a single source for the product version: VERSION at the repo root. During development, use X.Y.Z-dev; to release, change it to X.Y.Z on the release/X.Y.Z branch, and bump main to the next version with -dev. Production only ships commits without -dev.
  • Inject the version, commit, and deploy time at build time, and show them in plain words at the bottom of the page, like "App name 1.2.0 · updated 11-04"; do not show the manifest version.
  • Merging into the mainline does not mean it can be deployed: get approval before deploying, and run smoke tests after.
  • Reverse proxy: strip internal identity headers to prevent spoofing from outside; if you use SSE, set the read timeout to ≥3600 seconds.
  • Release the skill and CLI together: public repo releases include binaries for each platform plus sha256, checked at install time (see Agents using your app).
  • Make all environment-specific settings optional; never hard-code addresses or settings for a particular environment.

Pre-launch checklist

  • Completed the launch checklist (once each for embedded and new-tab opening)
  • manifest version is X.Y.Z and has been incremented
  • Embedded sign-in works on iPhone / iPad / desktop Safari (requestAuthCode)
  • No horizontal scrolling when embedded at phone width (390) (see Page UX guidelines)
  • The new version has been approved by an admin (a member's submission needs one admin's approval; new scopes are highlighted in the approval request)