Managing and Sharing Benchling Apps
The Benchling app framework provides features that make it easier to manage, install, and update apps across tenants. Benchling Apps support multiple versions, so developers can update their app manifest without disrupting existing installs. They can also be shared with multiple tenants, letting a single app be installed across dev, test, and prod environments, or across entirely different tenants for third-party apps. This guide covers those features, along with other app management features that support cross-tenant work.
Legacy apps
Some of the features described on this page are not available for legacy apps. Apps created before July 15, 2024, and all apps on GxP (validated cloud) tenants, are legacy apps. The Legacy Apps Overview covers the differences between the two frameworks.
App versioning
Benchling Apps are versioned. We recommend following semver best practices for versioning your app.
A version update is required if your app is already shared with at least one other tenant and you want to change the app manifest by adding or removing settings, app configurations, features, or subscriptions.
If an app is not already shared, you can upload a new instance of a manifest via the API without creating a new app version. Note that if your app is already installed on your home tenant, the manifest changes take effect immediately.
Installing an app on the home tenant
By default, apps created in your tenant are not automatically installed on it. This lets you iterate on an app’s settings, config, features, and event subscriptions without affecting any functionality in your tenant.
To install an app developed by a user on your tenant, go to Feature Settings > Developer Console > Apps and click the app to install. Navigate to Version History, select the version you want, and click “Install”:

On home tenants (those that own the app), you can switch between versions, so you can go back to an older version if you need to.
Sharing an app
Apps are shareable with other tenants. This helps when promoting an app from a dev to a test tenant and eventually to production, and it lets third parties distribute their apps more broadly.
An app version becomes immutable once it is shared. Making further changes after sharing requires creating a new version of the app.
To share an app, open it in the Developer Console and go to the Version History tab. Click “Share” to open a modal for sharing the app with other tenants:

Entering a valid tenant URL or ID generates an install URL you can copy from the UI. You need to click “Save” before that URL becomes valid.
An admin of the other tenant can then use the URL to install that specific version of your app on their tenant:

Apps shared with at least one other tenant require a valid webhook URL. On install,
Benchling sends a v2.app.installed
webhook to the app to inform the developer that it
has been installed. That webhook’s payload includes the ID of the installing tenant and
the app version installed.
Troubleshooting sharing issues
- Sharing is done per app version. Tenants with access to one version of your app do not automatically get access to newer or older versions; repeat the steps above for each version.
- If a tenant has an IP allowlist, sharing via tenant URL is not possible. Enter the
tenant_idin the share modal instead. - If the install URL appears inaccessible to a user of the installing tenant, check that
all of the following are true:
- The user is logged in.
- The user is a tenant admin.
- The user has FULL Developer Platform access.
- At least one app version is shared with that tenant.
Publishing an app
Apps with their Audience set to Public can request review by the Benchling team. Apps that have been reviewed and approved may be made fully public. Once an app is fully published, any Benchling customer can install it, whether or not they are on the allowlist.
Third-party apps available to install are listed under Technology Partners on Benchling’s partnerships page.
Updating an app
Installing tenants do not automatically get access to new versions of an app. A new version needs to be shared with them before their admin can upgrade.
Updating works the same way as installing. The same install URL shows an “Upgrade” button instead of “Install” if at least one version of the app is already installed on the tenant.

If the “Upgrade” button is grayed out, no newer version is available to that tenant.
It is not currently possible to select a specific version to install. Installing tenants always get the most recent app version available to them.
App activation
Apps that subscribe to the v2.app.activateRequested webhook show an “Activate” button in
the App Workspace.

Developers may add an Activate button if the app requires additional setup inside or outside Benchling after installation before it can function. Clicking “Activate” then tells the developer, through the webhook sent to the app, that setup is complete.
App deactivation and re-activation
Apps that use app activation can be deactivated. Deactivation revokes the app’s credentials, so the app can no longer make API calls in that tenant.

Deactivated apps remain in the App Workspace and can be re-activated. Re-activation makes the app’s existing credentials valid again, which typically means the app continues to function without further changes on the developer’s side.
Archiving apps
Currently, only app installations can be archived and unarchived. This can be done in
the App Workspace or in the Tenant Admin Console under /admin/apps. Like deactivation,
archiving revokes the app’s access to the Benchling API for that tenant. Archiving is
available for all apps, while deactivation is only available for apps that use an
activation flow.

App definitions in the Developer Console cannot yet be archived. In the future, app definitions with no active installs on the home tenant or any other tenant will become archivable.