Installation, consent & scopes

Apps declare their contributions and permissions in a manifest, but file registration and trusted installation authority are not the same thing. Marketplace installs a package's files and records its installation provenance. The platform then applies the consent rules for the package's capabilities.

A loose manifest can be useful while developing an ordinary app. It cannot stand in for a signed, consented WOPI or hosted-backend installation.

Signed installation

How an install runs

Installs run in the background on Marketplace's servers. The install wizard previews the whole dependency graph (your package plus the engines and apps it requires), the user consents once, and Marketplace queues the installation and returns straight away. The wizard, a corner tray and Workspace › Installations follow its progress; closing the wizard doesn't stop it.

• Phases. Progress is reported per phase: Verify signatures, one Install … row per package (percent from the package's bytes), an Editor row per WOPI editor, then Register in workspace.
• Concurrency. Several installs can run in one workspace at once. If two installs need the same dependency at the same version and location, one installs it and the other waits, then reuses it ("skipping — already installed"). A different package claiming an overlapping path is a conflict; the user can try again once the other install has finished.
• Clean failure. There is no cancel. If any phase fails, the remaining phases are skipped and everything this install added is removed in reverse order, so no partial install is left behind. A dependency that another install is already using is kept.
• Retry. A failed install can be retried from the wizard or from Workspace › Installations. Retrying previews the original request again against the workspace as it is now and asks for consent again.

Design packages so a failed or repeated install is harmless: keep installed files under your declared install paths, and don't rely on side effects from a partially installed version.

WOPI consent

For Collabora integration, the signed spec.wopi declaration identifies the wrapper and operator origins, file formats, actions, size/idle limits and optional rename/delete operations. The installer explicitly consents to the external editor processing document content. Both origins matter: the wrapper provider and the CODE operator may be different parties.

The install wizard asks for this consent before installing, in its Editor step: it shows the editor's host and operator, the file types it can view or edit, any rename/delete operations and its limits. Approving the install records the approval against the exact signed declaration, and the background install applies it once the editor is in place. If the approval can't be applied (for example, the declaration changed), the install fails and is removed like any other failure.

In-place updates ask the same way: when the new version declares an editor the workspace hasn't approved yet, the wizard shows the Editor step before Review, and once the update completes the approval is applied automatically, but only if the signed declaration is still the one that was reviewed. If it changed, the editor asks again. Packages that also declare a hosted backend still ask for editor consent after installing.

No publisher OAuth client registration is required for WOPI alone. A minimal WOPI-only wrapper can declare permissions: []; that does not let it bypass the user's file permissions. The host brokers WOPI launch and session controls.

If the package also declares a hosted backend, that backend retains its separate credential binding and consent. WOPI approval does not activate an unapproved backend, and backend approval alone does not grant WOPI document access.

Ordinary API permissions and OAuth

These fields concern ordinary platform API access or an app's separate OAuth identity, not a mandatory WOPI credential:

spec:
  permissions:                     # platform scopes the app needs
    - file.read
    - file.write

  oauth:
    client-type: public            # public (browser) or confidential (has a backend)
    redirect-uris:
      - https://app.example.com/auth/callback

  scopes:                          # custom scopes the app defines
    - acme-editor.document.export
    - acme-editor.settings.manage

App-to-app authorization

If your app needs to call another app's API, it must hold a grant for that app's defined scopes — enforced by the same token system that governs service-to-service calls. Define clear, well-named scopes so other developers (and admins) can reason about what they're granting.

Governance & visibility

Admins can see installed apps, the permissions each requests, and the scopes each defines, in the account → workspace views. Designing tight, legible permissions makes your app easier to approve and trust.

Updates, revocation and uninstall

Consent is bound to the exact reviewed candidate. Publish a new signed version for changes to origins, formats, limits, actions or optional operations, and complete the required consent review; changing installed files is not a way to expand authority. Do not assume approval of an old version approves a replacement.

Revoking installation consent invalidates its authority, including both WOPI and hosted-backend authority when both are present. Uninstall through the platform's installation flow rather than treating deletion of a manifest as a consent-only operation. Managed/seed payload handling follows the install-map lifecycle.

An open editor must handle denied or expired authority and preserve unverified edits. Never silently reacquire broader permission or report a pending save as successful after revocation.

Next