App types and manifest
The templates OpenMax apps currently support, plus the manifest (openmax.app.v1) fields, example, entry format, and validation rules at submission.
App types and manifest
An app = a manifest (openmax.app.v1) + a web page with a backend that you deploy yourself. This page covers what kind of app you can build today, how to write the manifest, and how it is validated at submission.
App types
| Template | Where it appears | How it gets identity | Status |
|---|---|---|---|
| Page app · with backend | Workspace Apps page / sidebar, embedded in an iframe or opened in a new tab | After approval an App ID is issued; the submitter or an admin generates an App Secret (shown only once, keep it on the backend). The app redirects to the authorization endpoint itself, and the backend exchanges code + code_verifier + App ID + App Secret for the current user's token | The only template today |
| Page app · frontend only (PKCE public client) | — | — | Deferred; writing public_client in the manifest is rejected (see "Reserved fields" below) |
- An iframe never gets the user's Workspace sign-in state, only tokens issued to this app.
- Agents cannot open apps (authorization returns
APP_PRINCIPAL_KIND_INVALID). If an AI agent does the work for you, the agent can submit the app; approval, generating the App Secret and the first-open acceptance check must be done by a human member.
manifest (openmax.app.v1)
The manifest is an allowlist: you may only write the keys listed below; any unlisted key returns unknown_field.
| Field | Required | Description |
|---|---|---|
schema |
Required | Always openmax.app.v1 |
slug |
Required | 2–63 characters: lowercase letters, digits, and -; reserved words not allowed; unique within the organization; cannot change in new versions |
name |
Required | Name shown on entries (name.zh required, name.en optional) |
description |
Optional | One-sentence summary |
icon |
Required | An https image URL, or 1–2 characters / an emoji |
version |
Required | Only three numeric parts X.Y.Z (such as 1.0.0); values like 1.0.0-beta are rejected; each submission must be greater than existing versions |
url |
Required | Your app's own web page (https); the shell opens url + sub-path. For host rules see "Validation rules" |
redirect_uri |
Required | Authorization callback URL (on your backend); its host must match the host of url. The redirect_uri sent in the authorization request and the token exchange must be byte-for-byte identical to it (case, trailing slash, and port all count) |
open |
Required | "embed" (iframe inside Workspace), "external" (new tab), or both |
entries[] |
Required | Entries, see "entries format" |
scopes[] |
Required | OpenMax permissions you need, chosen from the scope catalog (see "Scopes"); add offline_access to run while the user is away. The server automatically adds org:me:read, so you get it even if you omit it |
Two other kinds of keys cannot be written by developers:
- Reserved fields: these 9:
public_client,slot,events,capabilities,tools,surfaces,credential_mode,egress_domains,card_actions. Organization apps that set them getfield_not_enabled. - Platform-written fields:
regionsandpublisherare written by the platform. If a developer sets them, submission returnsfield_server_managed.
Example
{
"schema": "openmax.app.v1",
"slug": "my-app",
"name": { "zh": "我的应用", "en": "My App" },
"description": "One sentence on what this app does",
"icon": "M",
"version": "1.0.0",
"url": "https://my-app.example.com/",
"redirect_uri": "https://my-app.example.com/auth/openmax/callback",
"open": ["embed", "external"],
"entries": [
{ "path": "/", "title": "Home" },
{ "path": "/settings", "title": "Settings", "roles": ["owner", "admin"] }
],
"scopes": ["org:me:read", "org:me.email:read", "work:project:read"]
}
entries format
- 1–20 entries; one must have
path: "/". path: a sub-path starting with a single/, max 512, no whitespace,?,#, or\; no duplicates across entries.title: optional, a plain string, not per language (an object such as{ "zh": … }is rejected), max 40.roles: optional, fromowner/admin/member; omitted = visible to all members. It only controls who can see and open the entry; fine-grained permissions inside the entry are up to you.- Unknown keys (such as the old
slot) are errors.
For how an entry is selected and turned into the actual URL that opens, see Open modes and URLs.
Validation rules
Validated at submission; errors include the field path.
schemamust beopenmax.app.v1.slug: wrong format (not 2–63 lowercase letters, digits, and-), a reserved word, already taken in this organization, or changed in a new version are all errors.versionmust be three numeric partsX.Y.Zand greater than the current version.- Keys must be on the allowlist: unlisted keys return
unknown_field; the 9 reserved fields above returnfield_not_enabledfor organization apps; settingregionsorpublisherreturnsfield_server_managed. - Both
urlandredirect_urimust be https, and neither may contain userinfo (such ashttps://user@host/) or a#fragment. - Hosts of
urlandredirect_uri:- Lowercased and normalized to internationalized domain name (IDN) encoding before comparison.
- The host of
redirect_urimust match the host ofurl. - No IP addresses (a host ending in a digit counts as an IP).
- No single-label host names (such as
myapp). - No platform domains or their subdomains.
- None of these internal suffixes:
localhost,local,localdomain,internal,intranet,lan,home,corp,private,home.arpa,test,invalid.
redirect_urimust be byte-for-byte identical to the value used: the redirect_uri sent at authorization (including when requesting an authorization code from the host via requestAuthCode while embedded) and at token exchange must both be byte-for-byte identical to the value registered in the manifest (/callbackand/callback/are two different URLs).openmay only beembed/external, at least one, no duplicates.- Every item in
scopesmust be in the catalog and requestable by apps:apps:badge:writemay be requested; otherapps:*may not.- Umbrella scopes (
api,read_api) may not be requested.
