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).
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
Identity and sign-in
Permissions
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