Skip to navigation

Managing and Sharing Benchling Apps

How to version, install, share, and update Benchling Apps across tenants.

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”:

The Version History tab of an app, with the Install button for a specific version
Installing a specific app version on a home tenant

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:

The app share modal with a field for entering a tenant URL or ID
The share modal

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:

The app install page as seen by an admin of an installing tenant
The app install page

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_id in 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.

The app install page showing an Upgrade button for an available version update
An app with an available version update

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.

An app's workspace page showing an Activate button
An app with activation enabled

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.

A confirmation modal for deactivating a Benchling App
The app deactivation modal

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.

The App Workspace showing the archive option for an app installation
Archiving an app from the App Workspace

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.