Shareable Apps FAQ
Want to try Shareable Apps?
Contact your Benchling account team or Benchling support 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?
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:
- 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.
- Update your app to use the
/tokenendpoint 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 theclient_idandclient_secretvalues provided to this endpoint are no longer tenant-specific; they are the app’s only set of credentials. - Update your app to stop reading credentials from lifecycle webhooks, which no
longer applies to Shareable Apps. Most apps use a
MANUALlifecycle, in which case no change is required. Apps using anAUTOMATIClifecycle 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:
- 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?
- 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.
- 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:

Clicking it brings you to the app’s listing page, where the app definition lives in Benchling. The URL has the following format:
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.”