Installation, consent & scopes · Verentis Developer

Apps are first-class governed entities. They declare the identity and permissions they need in their manifest, and a workspace admin consents to them before the app goes live.

Install = manifest in the VFS

Installing an app means placing its *.app.yaml in the workspace file system (directly, or — coming soon — from the marketplace). Removing the manifest uninstalls it. By default uninstall is soft: the app's security resources are preserved so reinstalling restores its configuration. An optional cleanup removes them.

What gets registered

When your manifest declares an oauth client and custom scopes, those flow into the same security system that backend services use:

The manifest is detected

The app starts in a pending-consent state. It is registered but not yet active.

OAuth client & scopes are prepared

Your declared oauth.client-type and redirect-uris become an OAuth client; your custom scopes (e.g. smart-editor.document.export) are registered in the scope catalog alongside service scopes.

An admin consents

The workspace shows a consent screen listing the permissions the app requests and the scopes it defines. An admin must approve before the app becomes active.

The app goes live

Once consented, the app can be opened by users and receives tokens scoped to its granted permissions.

Declaring it in the manifest

spec:
  permissions:                     # platform scopes the app needs
    - node.file.read
    - node.node.create
    - node.node.update

  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

permissions

The scopes you request. These appear on the consent screen and bound the tokens you receive. Request the minimum.

oauth.client-type

public for browser-only apps; confidential if your app has a secure backend that can hold a secret.

scopes

Scopes you define so other extensions or services can be granted permission to call your app — this is the basis of app-to-app authorization.

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.

Status flags in these docs

The consent UI and full admin governance surfaces are rolling out. Where a step isn't yet available end-to-end you'll see a Soon badge — but the manifest fields you author here are the forward-compatible contract.

Local development

Iterate fast before you install.