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,
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.urlandredirect_uricannot 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"]
}
openonly listsexternal: the app opens in a new tab, and embedding is left for later.redirect_uriuses the same host asurl, and must match the code below byte for byte.
Step 2: Submit and get the App ID and App Secret
- On the Workspace apps page, click "Submit app" and paste
manifest.json. The page validates it right away and marks errors on the fields. - Once approved, the App ID (
app_…) is on the "My submissions" tab of the apps page. - On the same tab, click "Generate App Secret". It is shown only once: save it right away and keep it on the server only.
- 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
embedtoopenand 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.
