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

# Shareable Apps FAQ

> **Info**
>
> ### Want to try Shareable Apps?
>
> Contact your Benchling account team or [Benchling support](https://help.benchling.com/hc/en-us/requests/new)
> to get early access.

Benchling has released a new standard called **Shareable Apps** (formerly known as *Global
Apps*). Shareable Apps improve on the existing Benchling Apps framework, streamlining the
experience of creating and installing apps. Their identity and configuration details are
defined independently of the tenant where they were created, so they can be shared through
an install link and installed on any tenant without manifest uploads.

Because Shareable Apps are an improvement on the existing framework rather than a net-new
feature, it can be hard to see exactly how they differ from legacy Benchling Apps. This
page answers the most common questions.

## What are Shareable Apps?

A Shareable App is a Benchling App whose definition is stored globally, in a new
tenant-independent apps service. Legacy Benchling Apps, by contrast, stored their
definition only in the tenant where they were created.

This gives Shareable Apps a few advantages:

* App developers can create a single app definition, managed and updated in one place.
* App developers can share their app with any Benchling customer using a single install
  link.
* Tenant admins can install an app from a listing page, without working with local
  manifest files.

The result is an installation flow that resembles how users install apps in other systems,
plus a number of advantages for developers building, versioning, and distributing
Benchling Apps.

## How are Shareable Apps different from legacy Benchling Apps?

* Legacy Benchling Apps existed entirely within a single tenant, with no distinction
  between "creating" and "installing" an app. App framework features like App Manifest and
  App Configuration existed to improve usability and portability, but a distinct copy of
  the app had to be created in each new tenant, and maintaining consistency across many
  tenants meant depending on an external app manifest file.
* Shareable Apps live in a dedicated global service, and have a *definition* that exists
  apart from any specific *installation*. They are created once and can then be installed
  across multiple tenants. Because they install directly from that definition, they are
  fully portable between tenants, automatically consistent, and manageable in one place.

## What specific features and functionality differ?

### App creation

* **Previously:** there was little distinction between *creating* and *installing* an app.
  App definitions were created, directly or via a manifest, in the same tenant they were
  installed to, at the same time.
* **Now:** creation and installation are separate. App developers create and publish
  definitions in a single tenant; sharing and installing is done separately by tenant
  admins.

### App installation

* **Previously:** apps were installed when the definition was created in a tenant. Further
  manual intervention was required depending on whether the app was created "from scratch"
  or "from a manifest," and in both cases extra steps were needed to complete installation
  and activate the app.
* **Now:** Shareable Apps are installed directly from the app's listing page with a single
  click. Because the listing page is based on the tenant-independent definition, installing
  is completely distinct from creating.

### App versioning

* **Previously:** apps did not natively support versioning. Developers needed a new app
  manifest file for each new version, and tenant admins had to upload it, essentially
  creating a new app.
* **Now:** Shareable Apps natively support versioning. Developers can create, test, and
  publish new versions in their home tenant, and tenant admins can update installed apps
  in place.

### Versioned and unversioned data

* **Previously:** because apps did not support versioning, all data in the app definition
  was "unversioned." Updating it, such as a webhook URL or configuration options,
  required manual intervention by a tenant admin.
* **Now:** Shareable Apps support both versioned and unversioned data in app definitions.
  Versioned data can only be updated by publishing a new app version; unversioned data can
  be updated at will by the developer. Versioned data is data that directly affects a
  particular installation, like an app's configuration options or description. Unversioned
  data is tenant-agnostic and developer-managed, like an app's webhook URL and public key.

## How do I create and manage Shareable Apps?

The key difference is that the app *definition* is distinct from any particular
*installation*. A developer creates a definition in a single tenant, called the app's
**home tenant**. From there, they can publish new versions and update unversioned data.
Admins who want the app install it from that definition onto their own tenants; a tenant
that has installed an app is an **installing tenant**.

Managing the definition in the home tenant does not directly affect installations in
installing tenants. Unversioned data doesn't interact with installing tenants and can be
updated at will, while publishing a new version prompts installed tenant admins to
update.

## Are all Shareable App definitions publicly available?

No. All Shareable App definitions are stored in a global service and could potentially be
installed on any number of tenants, but access to a definition is managed by both
Benchling and the app developer. Shareable Apps have three levels of availability:

* **Private.** Intended to be installed by a single customer, though not necessarily a
  single tenant. A private app will never be published or distributed by Benchling outside
  that context.
* **Limited availability.** Intended for some number of customers, but not broad
  distribution. Benchling will not publish or distribute it, but it can be made available
  to a set of tenants based on an allowlist defined by the developer.
* **Public.** Intended for many customers and broad distribution. A public app can be
  published and distributed by Benchling, pending review, and is available to all tenants.

## What do I have to do to migrate my apps as an app developer? \[#migrate-as-a-developer]

Reach out to your Benchling representative to **enable Shareable Apps** in your tenant.
Once enabled, you will need to **recreate your app** as a Shareable App. After that, you
will likely need some modifications to your app code:

1. Update your app to **use a single set of credentials** instead of separate credentials
   per installed tenant. A Shareable App has a *single client ID and client secret* rather
   than a distinct pair per tenant. That one set of credentials is used to generate
   tenant-specific access tokens for each installing tenant.
2. Update your app to **use the `/token` endpoint** to create tenant-specific access
   tokens, if it doesn't already. Most apps already depend on `/token`, in which case no
   change is required. Note that the `client_id` and `client_secret` values provided to
   this endpoint are *no longer tenant-specific*; they are the app's only set of
   credentials.
3. Update your app to **stop reading credentials from lifecycle webhooks**, which no
   longer applies to Shareable Apps. Most apps use a `MANUAL` lifecycle, in which case no
   change is required. Apps using an `AUTOMATIC` lifecycle that obtained tenant-specific
   client credentials via a lifecycle webhook should use their app-specific credentials
   instead.

With those steps complete, your app can be installed on other tenants as a Shareable App.
Tenants with legacy installs should uninstall the old version and install the new
shareable one.

## What do I have to do to migrate my apps as a tenant admin with installed apps?

No immediate action is required to keep existing apps functioning. Migrating existing
legacy apps depends on who created them:

1. If **you or another user in your tenant** is the app developer, follow the steps under
   [What do I have to do to migrate my apps as an app developer?](#migrate-as-a-developer)
2. If **Benchling** is the app developer, your apps are likely already being migrated. If
   you haven't been contacted already, reach out to your Benchling representative.
3. If **a third party** is the app developer, contact them for details on when and how
   they will migrate the app.

## How do I install a Shareable App?

Shareable Apps have a **listing URL** they can be installed from. From the app's homepage
in the App Workspace of the home tenant, you'll find the App Listing button:

![An app's homepage in the App Workspace showing the App Listing button](/_fern-files/_img/8a3b2643358c886eb1fca563999a459c116806c0686caeb3c3841c41876c0adf.webp)

Clicking it brings you to the app's listing page, where the app definition lives in
Benchling. The URL has the following format:

```
https://<tenant_subdomain>.benchling.com/app-catalog/apps/<definition_id>/install
```

This URL is the mechanism for installing the app on other tenants. The `definition_id`
parameter is the app definition ID and remains constant. The `tenant_subdomain` parameter
is a particular tenant's subdomain, and varies with the tenant the app is being installed
to.

A tenant admin installing the app navigates to this URL using their own tenant subdomain
and the app's definition ID, where they'll see the listing page in their own tenant and can
click "Install."