Skip to content

Security & Trusted Sources

Installing apps from unknown sources

Only install apps from sources you trust

Installing a Forge app grants it access to your project. Read this page before installing any app that was not built and distributed by a party you fully trust.

Think before approving permissions

When you install or update an app, you will be shown exactly what permissions it is requesting before you confirm. Only approve permissions you understand and trust the app to use responsibly.

An app can only do what you allow it to do — but within those permissions, it can act freely. An app with write or delete permissions can modify or remove data without asking for confirmation each time. An app with read permissions can access that data and, if malicious, send it elsewhere. Permissions granted to a trusted source are safe; the same permissions granted to an unknown source are a risk.

Who to trust

Official Protokol marketplace apps — apps published through the official marketplace are reviewed and the publisher's identity is verified before listing. These are safe to install.

Apps from known, trusted developers — if you know the author and can inspect or have reviewed the source, you can make an informed decision.

Apps from unknown sources — .tar.gz bundles, links shared externally, or apps from publishers you cannot verify. Only install these if you fully understand and trust the permissions they are requesting.

App runtime token

When a user launches a Forge app, the platform issues a short-lived JWT scoped to that specific app session. The permissions embedded in this token are computed as follows:

token_permissions =
    (user_permissions ∩ runtime_permissions)   -- what the user can do, limited to what the app declared
    ∪ (entitlements ∩ available_permissions)    -- unconditional app-level permissions from the manifest
    ∪ (grants ∩ available_permissions)          -- additional permissions approved by an administrator

runtime_permissions (manifest-declared, user-intersected)

The app declares which permissions it wants at runtime in ptkl.config.js. At launch time, the platform computes the intersection of those declared permissions with the launching user's actual permissions. The app can never receive a permission the current user does not hold.

entitlements (manifest-declared, unconditional)

Entitlements are also declared in ptkl.config.js. Unlike runtime_permissions, they are merged into the token unconditionally — the launching user does not need to hold them. Use entitlements for service-level capabilities the app always needs regardless of who is running it.

Use entitlements carefully

Any user who can launch the app will cause the app to receive its entitlements. Only declare permissions as entitlements if every user of the app should allow the app to hold them.

grants (administrator-managed, unconditional)

Grants are additional permissions that a platform administrator has explicitly approved for a specific installation of the app on a specific tenant. Like entitlements, grants bypass the user-intersection step. They are managed through the app's Edit page and are stored per-installation, not in the manifest.

All unconditional permissions are bounded

Both entitlements and grants are filtered against the set of permissions that actually exist on the platform. A permission that has not been registered by any deployed app cannot appear in a token, even if declared as an entitlement or grant.