Scopes
Every scope an app can request.
Apps can request 88 scopes, grouped by domain below. Names follow domain:resource:action. For how to request scopes, how effective permissions are calculated, and sensitivity levels, see Calling platform capabilities.
- Used for: "API call" = calling the Apps API; "Event subscription" = receiving event pushes; "App-only" = not mapped to any endpoint; it acts on the token exchange (for example
offline_accessissues a refresh token; see Calling platform capabilities). - Which scope each endpoint needs: the Endpoints column links each scope to the endpoints that require it in the Apps API reference; every endpoint there also shows its scope. Titles and descriptions come from the platform scope list.
agents
apps
| Scope | Title and description | Used for | Endpoints |
|---|---|---|---|
apps:badge:write |
Show badges in Workspace Apps only: the app's backend sets a count or a dot on its Workspace entry for members of the organization (visible only to that member) | API call | PUT /api/v1/app-badges |
automations
billing
connections
kb
messages
org
| Scope | Title and description | Used for | Endpoints |
|---|---|---|---|
offline_access |
Offline access (refresh) Apps only: the token endpoint also issues a refresh token (30 days, rotated on every refresh), so the app can renew access while the member is away | App-only | — |
org:analytics:read |
View organization analytics Admin overview statistics | API call | GET /api/v1/analytics/overview |
org:invitation:accept |
Accept invitations Accept invitations sent to me (including invite-link tokens) and join a new organization, same as the web | API call | POST /api/v1/invitations/{invitation_id}/acceptPOST /api/v1/me/invitations/{invitation_id}/accept |
org:invitation:read |
View invitations Organization invitations, invitations sent to me | API call | GET /api/v1/invitationsGET /api/v1/me/invitations |
org:invitation:write |
Manage invitations Send and revoke invitations (invitable roles same as the web) | API call | POST /api/v1/invitationsDELETE /api/v1/invitations/{invitation_id} |
org:me.email:read |
Include my email in the sign-in token Apps only: decides whether the token response user.email and the id_token email claim carry the member's login email. It governs only those two places and does not gate GET /api/v1/me, which org:me:read grants and which returns the login email as on the web | App-only | — |
org:me:read |
View my basic info GET /api/v1/me (same response as the web, including the login email, the unverified contact email and the primary phone phone_cc / phone_number), list my stars (GET /api/v1/stars) | API call | GET /api/v1/meGET /api/v1/stars |
org:me:write |
Edit my profile Edit my avatar, language, contact email / phone, member display name; star / unstar (PUT / DELETE /api/v1/stars/{object_type}/{object_id}) | API call | POST /api/v1/avatars/uploads/finalizePOST /api/v1/avatars/uploads/preparePATCH /api/v1/mePATCH /api/v1/me/display-nameDELETE /api/v1/stars/{object_type}/{object_id}PUT /api/v1/stars/{object_type}/{object_id} |
org:member:read |
View members Member list / details (including email, as on the web), batch display-name lookup, a member's agents | API call | GET /api/v1/membersPOST /api/v1/members/batch-display-infoGET /api/v1/members/{member_id}GET /api/v1/members/{member_id}/owned-agents |
org:member:write |
Manage members Edit member profile / status / role, remove members (same as the web; the handler still requires owner/admin) | API call | POST /api/v1/members/batch-removeDELETE /api/v1/members/{member_id}PATCH /api/v1/members/{member_id} |
org:observation:read |
View member observation relationships Members I observe, observers of a member | API call | GET /api/v1/me/observed-membersGET /api/v1/members/{member_id}/observers |
org:organization:read |
View organization info Organization profile, organizations I belong to, pre-deletion check (read-only) | API call | GET /api/v1/organizationsGET /api/v1/organizations/{org_id}GET /api/v1/organizations/{org_id}/deletion-precheckGET /api/v1/organizations/{org_id}/storage-quota |
org:organization:write |
Edit organization profile Edit the organization name, avatar and other profile fields (the handler still requires owner/admin) | API call | PATCH /api/v1/organizations/{org_id} |
org:presence:read |
Receive presence events Member / agent presence changes (presence frames) | Event subscription | — |
org:role:read |
View roles List of available roles | API call | GET /api/v1/roles |
