Skip to main content

App marketplace

The marketplace lists partner apps that the operator of your PBX has reviewed and approved. An administrator installs an app for the company. The installed app signs in to your PBX through its own OAuth 2.1 authorization server, with exactly the permissions the app declared and never more. There are no payments in the marketplace.

Install an app​

Open Admin > Settings > Integrations > Marketplace (/admin/marketplace). You need integrations:read to browse and integrations:write to install and uninstall.

  1. Find the app under Available apps. Each entry shows the publisher, the version and the permissions it gets.
  2. Press Install. The dialog repeats the permissions: the app can sign in with these only, and each user still approves it on the consent page.
  3. The app now appears under Installed apps with its OAuth client ID. Give that id to the app. The app then runs its sign-in at your PBX.

To remove an app, press Uninstall under Installed apps. Every token of the app stops working at once. Installing and uninstalling are written to the audit log and raise integration.installed and integration.removed events with the connector marketplace:<app_id>.

How the limit works: an install registers an OAuth client in your company whose permission cap is exactly the app's manifest. At sign-in each user can grant the app only the requested permissions that are both in that cap and held by the user.

Review queue for the operator​

System administrators open Admin > App review (/admin/marketplace/review). You need system.settings:read to see it and system.settings:write to act.

A submission moves through these states:

submitted -> in review -> approved -> withdrawn
|-----> rejected

A submission can also be withdrawn from submitted or in review. Only approved versions are listed and installable. Rejected and withdrawn are final: the publisher submits a new version. A withdrawn app cannot be installed again, but companies that have it keep it until they uninstall.

Each submission shows its signed manifest and a licence and security checklist. Approve needs every item ticked, and Reject needs a note for the publisher:

  • Every bundled dependency has a permissive licence.
  • The licence and third-party notices are published.
  • No copyleft or source-available code runs inside the PBX.
  • Every requested permission is needed by a documented feature.
  • Every redirect address and webhook host belongs to the publisher.
  • Every endpoint uses HTTPS with a valid certificate.
  • The app verifies webhook signatures and the replay window.
  • Tokens are stored encrypted, never logged, and rotated.
  • A privacy policy says what call data is kept, where and for how long.
  • A security contact and a disclosure process are published.
  • Console extensions work in a sandboxed frame.

Publishers and signing keys​

On the same page, Publishers and signing keys lists the registered publishers with their signing keys and registers new ones (system.settings:write). Each publisher shows its name, security contact and id, and each key its id, its public key and whether it is active or revoked. Copy puts an id on the clipboard, and Revoke next to an active key revokes it after you confirm. Below the list, one card per action:

  1. Register publisher: a publisher id (2 to 40 lower-case letters, digits or hyphens, starting with a letter), a name and a security contact.
  2. Register signing key: a key id (3 to 64 lower-case letters, digits, dots, underscores or hyphens) and the Ed25519 public key as 44 base64 characters (32 bytes). The private key never leaves the publisher.
  3. To rotate, register a new key and revoke the old one with Revoke signing key. A revoked key verifies no new submission. Versions already reviewed stay as they are.

What a partner submits​

A partner signs the exact bytes of a manifest (schema 1, JSON up to 64 KiB) with its Ed25519 key and sends the manifest, the key id and the signature through the operator to POST /api/v1/system/marketplace/submissions. A signature from an unknown, revoked or another publisher's key, or one that does not match the bytes, is refused with MPBX-MKT-SIGNATURE. A manifest that does not follow the schema is refused with MPBX-MKT-MANIFEST-INVALID.

The manifest names the app id and version, the publisher, 1 to 32 permissions (never system.*), 1 to 8 redirect addresses, and optionally webhooks, console extension points and a connector description. Unknown fields are refused and every address must be https. Each version is a new submission.

API​

CallPermission
GET /api/v1/marketplace/apps, GET /api/v1/marketplace/installsintegrations:read
POST /api/v1/marketplace/apps/{app_id}/install, DELETE /api/v1/marketplace/installs/{app_id}integrations:write
Publishers, keys and the review queue under /api/v1/system/marketplace/...system.settings:read and system.settings:write

Good to know​

  • Partners submit apps through the operator, with a system credential.
  • Installing gives the app its OAuth client. It does not create webhooks, add console pages or run a connector on your PBX.
  • An install stays on its version. There is no update notice and no re-consent when a new version asks for other permissions.