Submission, approval and installation
How an app is submitted, who approves it, how it is installed / disabled / uninstalled; app badges; permission checks and audit your app does beyond scopes.
Submission, approval and installation
This page covers how an app goes from submission to being installed in an organization, and how to set a badge on a member's app entry. For which scopes (permissions) you can request, see "Scopes".
Submission, approval, installation
Submission
Apps page → "Submit app" → pick a template (manifest is pre-filled) → paste / upload manifest.json, or fill in the form (it produces the same manifest). The page validates as you go and marks errors on the fields. Both the Apps page and the submit page have a "Developer docs" drawer (Quick start / manifest fields / scope list / sample code).
For manifest fields and validation rules, see App types and manifest.
Visibility and approval
| Organization app | Global app | |
|---|---|---|
| Who can see it | This organization | All organizations (listed in the directory) |
| Who approves | Admins of this organization (owner / admin); the approver cannot be the submitter; submissions by admins / super admins are approved automatically | The platform (not open to external developers yet) |
| URL | /workspace/apps/custom/{slug}-{4 random chars} |
/workspace/apps/{slug} |
- Third parties can currently only build organization apps. Global apps listed for all organizations are not open to external developers yet.
- Any member can submit a new app and publish a new version of any app in their organization. Every new version submitted by a member who is not an admin, or by an Agent, needs one admin's approval.
- After the first approval, the app gets a platform link and an App ID.
- The submitter or an admin clicks "Generate App Secret": it is shown only once and can be rotated; after rotation the old Secret stays valid for 24 hours, with at most two active at a time.
Install, disable, uninstall
- Install to an organization: an organization app is installed in its own organization automatically after its first approval; there is no separate install step. "Install" / "Request install" only apply to apps in the directory (global / official apps): admins install directly; members can only "Request install", which an admin approves. There is no per-member consent: the scopes the admin approves at install time are the scopes of every member's token.
- Disable: the entry disappears, all issued access tokens stop working (within 30 seconds), API calls from the app return 401, and the authorization callback returns
access_denied. After re-enabling, users just open the app again. - Uninstall: the entry is removed; the App Secret and all refresh tokens are revoked; the URL is retired and never reused. This cannot be undone.
- When a member leaves the organization: that member's refresh tokens are revoked too.
- The platform does not notify the app of these changes: treat a 401 as authorization being gone, and do not retry forever.
App badge
Status: Live.
An app can set a badge (a number or a red dot) for members of an organization. It shows on the app's entry in Workspace, for example "You have 7 pending approvals". Badges are written by the app's server, authenticated with App ID + App Secret, and do not need the member to be online.
Enable
- Add
apps:badge:writetoscopesin the manifest. - Submit a new version. A version submitted by a member needs one admin's approval, and the approval request highlights the new scopes; an admin's own submission is approved automatically.
- It takes effect once the new version is approved.
Write API
PUT /api/v1/app-badges
Authentication: App ID + App Secret only, using one of these two:
- HTTP Basic (username App ID, password App Secret);
app_id/app_secretin the request body.
Sending both returns 400. Bearer tokens are not accepted (a member's access token cannot be used to write badges).
Request body:
{
"org_id": "…",
"items": [
{ "member_id": "…", "count": 7 },
{ "member_id": "…", "dot": true },
{ "member_id": "…", "count": 0 }
],
"as_of": "2026-11-06T09:30:00Z"
}
| Field | Description |
|---|---|
org_id |
Required. The organization whose badges you are writing |
items |
Required, 1–500 items |
items[].member_id |
Required. The same member_id cannot appear twice in one request |
items[].count |
Number badge, 1–1000000; 0 clears it |
items[].dot |
true shows a red dot; false clears it |
as_of |
Optional, RFC 3339 time, at most 5 minutes ahead of server time |
- Each item takes only one of
countanddot. - With
as_of, an olderas_ofnever overwrites a newer value and never brings back a cleared badge. Requests that arrive out of order will not roll a badge back to an old value.
Response:
{ "data": { "applied": 3, "cleared": 1, "skipped": 0 } }
applied: number of items set.cleared: number of items cleared.skipped: number of items skipped, i.e. not active members of that organization (including Agents). The response does not say why.
Errors: the response body is HTTP problem JSON.
| HTTP | Error code | Meaning |
|---|---|---|
| 400 | — | Invalid request, e.g. empty items, both count and dot in one item, both Basic and body credentials sent |
| 422 | — | Field validation failed, e.g. more than 500 items, unknown field |
| 401 | AUTH_INVALID_CREDENTIALS |
Wrong App ID / App Secret |
| 403 | APP_INSTALLATION_INACTIVE |
The app is not installed in that organization, or is disabled |
| 403 | AUTH_APP_INSUFFICIENT_SCOPE |
The install did not approve apps:badge:write |
| 429 | APP_BADGE_RATE_LIMITED |
Rate limit exceeded; wait as given by the Retry-After header, then retry |
Rate limit: 120 requests per minute per install. The limit is approximate, not an exact cap; do not treat it as a quota you can use up.
Lifecycle
- When the app is uninstalled, all its badges are deleted.
- Badges are not shown while the install is disabled.
Display
- Numbers above 99 show as "99+".
- The page does not poll badges. They refresh on: page load, switching apps, and returning to the window.
- Moving between pages inside the same app does not refresh badges.
Suggested use
- When one person's count changes, send one request with just that person.
- Also send a full sync every few minutes, 500 people per batch, to fix missed or failed writes.
- Both kinds of request can include
as_of(the time of the data), so late, older data does not overwrite newer data.
Permissions and audit
Platform rules: "scope", "Submission, approval, installation" above, "token", "Publishing new versions", and "Error handling". Effective permissions = approved scopes ∩ the person's own permissions. The platform has no action-scoped authorization, and no audit requirements or audit API. Below is how the reference implementation (OpenMax Workflows) does it. These are recommendations, not platform requirements.
Permissions
Recommended
- Owners grant agents use of your app: the owner clicks "Let it use this", and the server calls
/api/v1/app-agent-grantsto register it; admins can revoke it on the OpenMax side (see Agents using your app). - When you need "only allow it to do this kind of thing", enforce the limit in your app.
- Second confirmation for high-risk writes: first run a dry_run that returns the list of changes and a digest, then submit with confirm_digest. The digest only proves "this list was seen"; it is not an authorization credential, and permissions are still checked as usual.
- Widening permissions requires confirmation; narrowing can be applied directly.
- When acting on behalf of people, permissions are the lower of the two (speaker and agent).
Pitfalls
- After adding a scope to the manifest, you cannot use it until the new version is approved, and even then old tokens cannot get the new scope. Show the missing-scope message to both the organization admin (to approve) and the user (to sign in again).
Audit
Recommendations
- Record every write: who, from which entry point, did what. Keep entry points distinct, for example: web session, personal key, system, OpenMax sign-in, agent on behalf.
- Also record rejected writes (allowed=false). To avoid flooding, you can merge: for the same key, write only the first 5 rows within 10 minutes, then one summary row.
- Record the person for delegated actions: when an agent acts for someone, record the entry point as "delegated" and the actor as the person who spoke, not the agent.
- Audit sign-ins too: record sign-ins from OpenMax; for embedded header-based sessions, also record the delivery method and the browser family, not the full UA.
- Keep secrets out of the audit: auth codes, verifiers, nonces, tokens, passwords, and session IDs never go into logs, audit records, or responses; business content stays out of audit details too.
- Tamper resistance: the audit table is append-only (triggers block UPDATE / DELETE / TRUNCATE), with a hash chain (each row stores the previous row's hash).
- Ops checks must read the audit table: a green health check does not mean the database is readable, so routine checks must actually read the audit table.
Why we recommend it
- The platform does not notify your app when it disables the app or revokes a grant. If something goes wrong, only your own records can reconstruct "who did what, and when".
- When agents act on behalf of people, without an audit you cannot tell whether a person or the agent did it.
