> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# 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.

> **Info**
>
> ### 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](/docs/legacy-apps-overview) covers the differences
> between the two frameworks.

## App versioning

Benchling Apps are versioned. We recommend following
[semver best practices](https://semver.org/) 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](/docs/api/v2-beta/benchling-api-beta/app-definitions/put-benchling-app-definition-version-manifest)
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](/_fern-files/_img/bdf2f7e89a34a1661b09c1f91b7b88ca6489eef4c2b42de8518291ffe940b11c.webp)

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](/_fern-files/_img/f0793f0829cab95f2215f5c08d16f8b4741b264a4331c06365eda32d921cca06.webp)

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](/_fern-files/_img/eba3ffb871d6a6c3ae8b70d8561ac515c48ca23a0acc3c85d15671c7b12659a8.webp)

Apps shared with at least one other tenant require a valid webhook URL. On install,
Benchling sends a `v2.app.installed`
[webhook](/docs/getting-started-with-webhooks) 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](https://www.benchling.com/partnerships).

## 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](/_fern-files/_img/74f140895cb5a3a133ef70afcf3eddb72f2bb1bb5781eb0b98bd16328137ae7e.webp)

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](/_fern-files/_img/c04ea6e7de7dfd3b721409ab70768afd4fc8a96366595f35a54fc9ed5c0fa07c.webp)

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](/_fern-files/_img/0f0b0ce0e124d2219b566f61f92697ad128f4873dd0aaf82f67016237fb6413b.webp)

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](/_fern-files/_img/86e0548000367ccad9a9585e18e73e92f69c8f399d51d82901bba52e1ac0fdde.webp)

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.