OpenMax
Free Trial

Calling platform capabilities

Whom the app's token represents and how permissions are computed; which scopes you can request; what the platform offers today (available, coming soon, not yet, not planned).

Calling platform capabilities

Tokens

  • Personal tokens only: a token represents the person using the app. There is no app identity token and no organization-level token.
  • Effective permissions = approved scopes ∩ the person's own permissions. For example, if the app is approved for work:project:write, a member without that permission still gets 403.
  • Access tokens last 15 minutes. When one expires, the app itself goes through the authorization endpoint again (seamless if the user is signed in to Workspace); the shell is not involved. When embedded, ask the host for a new authorization code instead; see Sign-in ("Sign-in when embedded").
  • No refresh token by default. If the app must run while the user is away (scheduled jobs, overnight sync), request offline_access in the manifest; refresh tokens are issued only after approval (30 days, rotated on every refresh).
  • The user identifier is member_id (= sub): stable for the same person within one organization. The app keeps its own accounts and mapping; we suggest binding on (issuer, org_id, member_id) (the same person has a different member_id in each organization; for binding boundaries see Integrating existing systems).
  • The email in the token response / id_token requires org:me.email:read (GET /api/v1/me is not controlled by it). Do not use email as a binding key.
  • Agents are peers of users and call Workspace with their own credentials, not through app authorization. If an Agent needs to call back into your app, there are two ways: the platform's Agent app token + owner grant (recommended, see Agents using your app), or your app issues the Agent its own API key.

For the scope list, see "Scopes (permissions)" below.

Scopes (permissions)

  • Apps share the same scope directory as personal API keys (PAT), named domain:resource:action. The scope list on the submit page reads from the directory (GET /api/v1/app-scopes).
  • Scopes in the directory are open to apps; only these two kinds cannot be requested:
    • apps:* app management scopes: only apps:badge:write can be requested (see "App badge" below); none of the others can.
    • Umbrella scopes (api, read_api): cannot be requested; select each scope individually.
  • org:me:read is added automatically by the server, even if the manifest does not list it.
  • Levels: each scope has a sensitivity level: L0 normal, L1 sensitive, L2 highly sensitive. Levels are shown only at approval and install time: submission and approval cards show the highest level the app requests, and installing an app whose highest level is L2 shows a red warning. Levels do not affect permissions: what a token can do is still "approved scopes ∩ the person's own permissions". Examples: org:me:read is L0; org:member:read and sending messages are L1; reading message content and reading the knowledge base are L2.
Category scope Description Covers Level
Self org:me:read Basic info about the user (added automatically) GET /api/v1/me L0
Directory org:member:read Member list and details GET /api/v1/members L1
Projects and tasks work:project:read View projects GET /api/v1/projects L0
Projects and tasks work:project:write Create / advance projects POST /api/v1/projects L1
Projects and tasks work:issue:read View Issues GET /api/v1/projects/{project_id}/issues L0
Projects and tasks work:issue:write Create / advance Issues POST /api/v1/projects/{project_id}/issues L1
Projects and tasks work:task:read View Tasks GET /api/v1/tasks L0
Projects and tasks work:task:write Create / advance Tasks POST /api/v1/projects/{project_id}/issues/{issue_id}/tasks L1
Conversations and messages messages:conversation:read Conversation list and details GET /api/v1/conversations L1
Conversations and messages messages:message:read Read messages GET /api/v1/conversations/{id}/messages L2
Conversations and messages messages:message:send Send messages as the user POST /api/v1/conversations/{id}/messages L1
Knowledge base kb:space:read View knowledge bases GET /api/v1/kbs L2
Knowledge base kb:page:read View knowledge base pages GET /api/v1/pages/{page_id} L2
App-only offline_access Run as the user while they are away (issues a refresh token) refresh_token in the token response L1
App-only org:me.email:read Return the email when exchanging the token user.email in the token response and email in the id_token L1
App-only apps:badge:write Set app badges for members of this organization PUT /api/v1/app-badges L1

The table lists common scopes; the directory (the "scope list" in the Developer docs drawer) is the full, authoritative list.

API reference coming soon. In this release, the app APIs are mainly for sign-in and identity (see "Confirm identity and membership with /api/v1/me" in Sign-in).

For how effective permissions are calculated and how tokens are issued, see "Tokens" above.

Capability list

Each item states whether it is available today. For usage and details, see the matching section of each page, or the Chat SDK docs.

  • Available: live (openmax.com).
  • Coming soon: not available yet, going live shortly.
  • Not yet available: the docs say it is deferred, with no decision on whether it will be built.
  • Not planned: the platform explicitly lists it as out of scope for this phase.

App types and hosting

Capability Status Details
Page app with a backend Available "App types"
Frontend-only app (PKCE public client) Not yet available (will be rejected) "App types" and "Out of scope"
Platform-hosted app backend Not yet available (deploy the backend yourself) "Out of scope"

Opening and embedding

Capability Status Details
Open embedded / in a new tab, multiple entry points Available "manifest" and "Open modes and URLs"
New-tab fallback when embedding fails Available "Open modes and URLs"
Theme and language parameters on the entry URL, pushed on change Available "Parameters on the entry URL"
Route sync (openmax:location) Available "Route sync"
App requests to open a chat (navigate, openChat({memberId})) Coming soon "App requests to open a conversation"
Host-driven app navigation, iframe size negotiation, query / hash sync Not planned (not in this phase, no date) "Out of scope"
General postMessage bridge Not yet available (deferred) "Out of scope"
Calling host capabilities Not yet available "Out of scope"
App badge (apps:badge:write) Available "scope" and "App badge"
@openmaxai/app-sdk (wrapper library for the protocol) Not yet available (not published to npm; implement the protocol yourself) "Parameters on the entry URL"

Identity and sign-in

Capability Status Details
Redirect sign-in: OAuth 2.0 authorization code + PKCE + id_token Available "Sign-in: app-initiated authorization"
refresh_token (offline_access) Available "Token endpoint and tokens"
Embedded sign-in requestAuthCode Available "Sign-in when embedded"
Host prompts apps without requestAuthCode to switch to a new tab Not planned (do not rely on a host prompt; WebKit shows a blank page, so embedded apps must implement requestAuthCode) "Sign-in when embedded"
Unified SSO (shared sign-in state, sign-out notification) Not yet available "Session lifetime" and "Out of scope"
App identity token / organization-level token Not planned (not in this phase; see for alternatives) "Tokens" and "Out of scope"
Agent opens an app Not yet available "App types"
Agent app token + owner grant Available (preview: request and response formats not yet public) Agents using your app

Permissions

Capability Status Details
Scope catalog (shared with personal API Keys) Available "scope"
Install approval, new version approval (every new version submitted by a member needs one admin's approval) Available "Submission, approval, installation" and "Publishing new versions"
Tokens invalidated after disabling Available (the platform does not notify the app) "Install, disable, uninstall"
Per-user consent Not yet available "Install, disable, uninstall"
Action-scoped authorization, second confirmation for high-risk operations Not yet available (the app does it itself) Submission, approval and installation ("Permissions and audit")

Chat (Chat SDK)

Capability Status Details
@openmaxai/chat-sdk and the other three packages, 3.0.0-beta.5 Available (beta, API not frozen; pin the exact version) Chat SDK docs
Conversation list, message threads, split layout, interactive cards Available Chat SDK docs
Read-only progress of agent execution Available (experimental) Chat SDK docs
Click an avatar to open a DM (openConversation({ memberId })) Available Chat SDK docs
DM with context (context sub-conversation) Coming soon Chat SDK docs
Agent runs (stoppable, run list), approval cards Planned (no date) Planned; no public docs yet
Credentials: personal API Key on the server, exchanged for short-lived tokens Available (the only path the docs describe) Chat SDK docs
Credentials: app OAuth token Used by the reference implementation; not yet in the docs Chat SDK integration

Audit and release

Capability Status Details
Platform audit requirements / audit API for apps Not yet available Submission, approval and installation ("Permissions and audit")
App Secret rotation Available "Visibility and approval"
Launch checklist Available (docs) "Launch checklist"