OpenMax
Free Trial

Quick start

Get a minimal OpenMax Workspace app running in 5 minutes: write a manifest, submit it, sign in with OpenMax, and show the current member on the page.

Quick start

Follow these 5 steps to build a minimal Workspace app: open it from Workspace, sign in with OpenMax, and the page shows "Hello, ". The code is a single Node.js file.

To keep this page short, it only covers "open in a new tab". To open the app embedded in a Workspace page, sign-in must use requestAuthCode instead; see step 5.

Before you start

  • Node.js 20 or later.
  • A domain reachable from the internet over https, pointing at the machine running your server, for example https://hello.example.com. url and redirect_uri cannot use localhost, an IP or an internal domain (rules in App types and manifest). For local development you can use a public https tunnel: under the current host rules a tunnel-service domain is not rejected, but the platform has not explicitly committed to this.
  • You are in an OpenMax organization. Apps submitted by an organization admin are approved automatically; if you are not an admin, step 2 waits for an admin to approve.
  • If an AI agent does this for you: the agent can submit the app; approval, generating the App Secret and the first-open acceptance check (step 4) must be done by a human member.

Step 1: Write the manifest

Save the following as manifest.json, replacing hello.example.com with your domain:

{
  "schema": "openmax.app.v1",
  "slug": "hello-openmax",
  "name": { "zh": "你好 OpenMax", "en": "Hello OpenMax" },
  "description": "Minimal example that shows the signed-in member",
  "icon": "H",
  "version": "1.0.0",
  "url": "https://hello.example.com/",
  "redirect_uri": "https://hello.example.com/callback",
  "open": ["external"],
  "entries": [{ "path": "/", "title": "Home" }],
  "scopes": ["org:me:read"]
}
  • open only lists external: the app opens in a new tab, and embedding is left for later.
  • redirect_uri uses the same host as url, and must match the code below byte for byte.

Step 2: Submit and get the App ID and App Secret

  1. On the Workspace apps page, click "Submit app" and paste manifest.json. The page validates it right away and marks errors on the fields.
  2. Once approved, the App ID (app_…) is on the "My submissions" tab of the apps page.
  3. On the same tab, click "Generate App Secret". It is shown only once: save it right away and keep it on the server only.
  4. Once approved, an organization app is installed in your organization automatically; there is no separate install step.

Details: Submission, approval and installation.

Step 3: Write the server

mkdir hello-openmax && cd hello-openmax
npm init -y && npm pkg set type=module
npm install express@5 jose

Create server.js:

import crypto from "node:crypto";
import express from "express";
import { createRemoteJWKSet, jwtVerify } from "jose";

const ISSUER = process.env.OPENMAX_ISSUER || "https://openmax.com"; // OpenMax address: https://openmax.com
const APP_ID = process.env.OPENMAX_APP_ID;
const APP_SECRET = process.env.OPENMAX_APP_SECRET; // server side only
const ORG_ID = process.env.OPENMAX_ORG_ID; // your organization id: only members of this organization get in
const REDIRECT_URI = "https://hello.example.com/callback"; // byte-for-byte the same as the manifest
const JWKS = createRemoteJWKSet(new URL(`${ISSUER}/api/v1/apps/jwks`));
const rnd = () => crypto.randomBytes(32).toString("base64url");
const same = (a, b) => { const x = Buffer.from(a), y = Buffer.from(b); return x.length === y.length && crypto.timingSafeEqual(x, y); }; // constant-time comparison for state
const flows = new Map(); // in-memory for the demo; real apps use server-side storage, 10-minute expiry, single use
const sessions = new Map();
const cookieOf = (req, name) => (req.headers.cookie || "").split("; ").find((c) => c.startsWith(name + "="))?.slice(name.length + 1);
const COOKIE = "Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=900";

const app = express();

// Home: greet if signed in, otherwise go sign in
app.get("/", (req, res) => {
  const user = sessions.get(cookieOf(req, "sid"));
  if (!user) return res.redirect("/login");
  res.send(`<h1>Hello, ${user.name.replace(/[<>&"]/g, "")}</h1><p>Organization: ${user.orgId}</p>`);
});

// Start authorization: authorization code + PKCE, with state and nonce
app.get("/login", (req, res) => {
  const flow = { id: rnd(), state: rnd(), nonce: rnd(), verifier: rnd() };
  flows.set(flow.id, flow);
  res.setHeader("Set-Cookie", `flow=${flow.id}; ${COOKIE}`);
  const q = new URLSearchParams({
    response_type: "code", client_id: APP_ID, redirect_uri: REDIRECT_URI,
    state: flow.state, nonce: flow.nonce,
    code_challenge: crypto.createHash("sha256").update(flow.verifier).digest("base64url"),
    code_challenge_method: "S256",
  });
  res.redirect(`${ISSUER}/api/v1/apps/authorize?${q}`);
});

// Callback: check iss and state, exchange the code, verify id_token, check sub and organization
app.get("/callback", async (req, res) => {
  const fail = (why) => { console.log("sign-in failed:", why); res.status(400).send("Sign-in failed, please open the app again"); }; // the reason goes to the server log only; the browser just sees "Sign-in failed"
  const flow = flows.get(cookieOf(req, "flow"));
  flows.delete(cookieOf(req, "flow"));
  if (!flow || req.query.iss !== ISSUER || !same(String(req.query.state ?? ""), flow.state)) return fail("flow, iss or state");
  if (req.query.error) return res.status(403).send(`Sign-in failed: ${String(req.query.error).replace(/[<>&"]/g, "")}`);
  try {
    const r = await fetch(`${ISSUER}/api/v1/apps/token`, {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "authorization_code", code: String(req.query.code), redirect_uri: REDIRECT_URI,
        code_verifier: flow.verifier, client_id: APP_ID, client_secret: APP_SECRET,
      }),
    });
    if (!r.ok) return fail("token " + r.status + " " + (await r.text())); // the body only has error and error_description, no secrets
    const { id_token, access_token } = await r.json();
    const { payload } = await jwtVerify(id_token, JWKS, { issuer: ISSUER, audience: APP_ID, algorithms: ["RS256"] });
    if (payload.nonce !== flow.nonce || payload.sub !== payload.member_id) return fail("nonce or sub");
    if (payload.org_id !== ORG_ID) {
      console.log("rejected org_id:", payload.org_id); // on the first run you can leave OPENMAX_ORG_ID unset and read your organization id from this log line
      return res.status(403).send("Not a member of this organization"); // members of other organizations are rejected
    }
    const me = await fetch(`${ISSUER}/api/v1/me`, { headers: { Authorization: `Bearer ${access_token}` } }); // call the API with the access_token
    if (me.ok) console.log("me:", (await me.json()).data.display_name); // /api/v1/me wraps its fields in data
    const sid = rnd();
    sessions.set(sid, { name: payload.name, orgId: payload.org_id, memberId: payload.member_id });
    res.setHeader("Set-Cookie", `sid=${sid}; ${COOKIE}`);
    res.redirect("/");
  } catch (e) {
    fail(e.code || e.message); // bad signature, expired token, network error: treat as a failed sign-in and do not send error details to the browser
  }
});

app.listen(3000, () => console.log("listening on :3000"));

Run it (put port 3000 behind your https domain). OPENMAX_ORG_ID is your organization id: on the first run you can leave it unset, sign in once, take it from the rejected org_id: line in the server log, then restart with it. After a successful sign-in the server log prints me: and your name, fetched from /api/v1/me with the access_token (the fields are in the response's data; see Sign-in).

OPENMAX_APP_ID=app_xxx OPENMAX_APP_SECRET=xxx OPENMAX_ORG_ID=your_org_id node server.js

Step 4: Open it from Workspace

In the Workspace sidebar, click "Hello OpenMax", then "Open in new tab". The first time you are sent to OpenMax to authorize; when you come back the page shows "Hello, ".

If it does not open, check these first:

Symptom Most likely
The authorization page says redirect_uri is wrong REDIRECT_URI in the code is not byte-for-byte the same as the manifest
The callback says "Sign-in failed" and the log says sign-in failed: flow, iss or state The callback check failed: the flow cookie did not come back (the domain is not https, or you switched browsers), iss is not OPENMAX_ISSUER, or state is wrong
The callback says "Sign-in failed" and the log shows sign-in failed: followed by nonce or sub or a verification error The id_token check failed: wrong signature, aud, expiry, nonce or sub
The page says "Not a member of this organization" Normal on the first run (before OPENMAX_ORG_ID is set): take your organization id from the rejected org_id: line in the server log; if it still appears after you set it, the value is wrong
The authorization page asks you to "Switch to {organization} and continue" (APP_ORGANIZATION_MISMATCH) The app belongs to another of your organizations; click switch
The callback says "Sign-in failed" and the log says sign-in failed: token … Token exchange failed; the log has the status and error: wrong App Secret; the code was already used (once only) or exchanged more than 60 seconds after you got it; REDIRECT_URI differs from the one used at authorization
Authorization returns access_denied The app is not installed in this organization or is disabled, or your role cannot see any entry

Step 5: Next steps

  • Open it embedded in a Workspace page: add embed to open and sign in with requestAuthCode; see Sign-in ("Sign-in when embedded").
  • Full handling of session expiry, identity re-checks and errors: see End-to-end examples and Sign-in.
  • Before launch, go through the Launch checklist.
  • Choosing an integration path, reference implementations and common pitfalls: see "Pick a path for your situation" on the developer home.