OpenMax
Free Trial

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 get field_not_enabled.
  • Platform-written fields: regions and publisher are written by the platform. If a developer sets them, submission returns field_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, from owner / 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.

  • schema must be openmax.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.
  • version must be three numeric parts X.Y.Z and greater than the current version.
  • Keys must be on the allowlist: unlisted keys return unknown_field; the 9 reserved fields above return field_not_enabled for organization apps; setting regions or publisher returns field_server_managed.
  • Both url and redirect_uri must be https, and neither may contain userinfo (such as https://user@host/) or a #fragment.
  • Hosts of url and redirect_uri:
    • Lowercased and normalized to internationalized domain name (IDN) encoding before comparison.
    • The host of redirect_uri must match the host of url.
    • 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_uri must 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 (/callback and /callback/ are two different URLs).
  • open may only be embed / external, at least one, no duplicates.
  • Every item in scopes must be in the catalog and requestable by apps:
    • apps:badge:write may be requested; other apps:* may not.
    • Umbrella scopes (api, read_api) may not be requested.