App catalog and switcher
App catalog and switcher
Environment administrators publish apps under Developers → App catalog. The navigation switcher and dashboard read this catalog. OAuth client registration alone does not publish an app, and catalog visibility does not grant app access.
Create a stable lowercase key, name, optional description, explicit HTTPS launch URL and position. Upload a PNG, JPEG or WebP icon (128 KiB / 512 pixels maximum), or use the automatic initials fallback. Icons are public assets served by ID; do not upload confidential artwork. Drafts stay hidden until published.
Choose everyone in the environment, selected organizations, or selected users. Organization visibility requires active membership and an active organization. An optional feature flag further narrows visibility. Related environment-wide OAuth clients are references only; several integrations can belong to one app.
Read the person's apps
GET /api/v1/me/apps requires a delegated person token with
account:apps:read, under the existing account API authentication contract
(management resource audience <issuer>/mcp, including DPoP where required).
An environment key or a token issued only for another API is not a person token.
Optionally pass organization_id to narrow the result to the selected active
membership. A token confined to an organization cannot select a different one.
Without it, the list covers the person's active organizations.
The response contains data entries with key, name, description,
launch_url, icon_url, position, and version. meta.revision hashes that
visible list; meta.refresh_after is 60 seconds. Administrative audiences,
OAuth client IDs and icon bytes are not included.
Render the returned order with ordinary cross-app links. Cache only per issuer, person and selected organization. Refresh on focus/open when stale and while visible, and clear on logout or context changes. A server response is private and not HTTP-cacheable. There is no catalog-change webhook in this release. Icons use content-addressed public URLs; allow the issuer in your image CSP and show initials when an image fails.
Management API
GET /api/v1/app-catalogandGET /api/v1/app-catalog/{key}requireapp_catalog:read.PUT /api/v1/app-catalog/{key}requiresapp_catalog:write; send the full entry withversion: 0to create, or the version read to update.DELETE /api/v1/app-catalog/{key}requiresapp_catalog:writeand the currentversion.
A stale edit/delete returns 409. Reload and review before retrying. PUT omits
icon to retain it, uses null to clear it, or a supported image data URI to
replace it. A no-op does not bump the version. Saves and deletions are audited
without copying the icon or target lists into the audit context.
See the environment actions and
account actions for the generated schemas.
The cbox-design skill's references/app-switcher.md defines the common desktop
and mobile UI contract for rolling this out to other Cbox products.