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

# Legacy Apps Overview

Benchling released a new version of the app framework in July 2024 alongside the
announcement of [Shareable Apps](/docs/global-apps-faq). While most tenants already
support Shareable Apps, a full migration to the new framework is still in progress:

* GxP tenants do not currently have access to the new app framework. All apps on GxP
  tenants are legacy apps.
* All apps created on any tenant before the GA release of the new framework on
  July 15, 2024 are still legacy apps.

At some point in the future, all apps across all tenants will be migrated to the new app
framework automatically. Until then, this guide covers the key differences between the two
frameworks and what to consider when working with legacy apps.

## App definitions and installations

For legacy apps, there is no distinction between an **app definition** and an **app
installation**. All apps on a tenant appear both under Connections > Apps and under
Feature Settings > Developer Console > Apps.

In the new framework, definitions and installations are distinct. A user should never be
able to modify an app owned by another tenant, so apps that are installed but not owned by
the tenant do not show up in the Developer Console.

![The Developer Console Apps list, showing only apps owned by the tenant](/_fern-files/_img/307581bd138d9be631044642e580500018d7402281a446bcfa0704876b297ddb.webp)

What appears in the Developer Console is the **app definition**.

Installed apps not owned by the tenant only appear in the App Workspace under
Connections > Apps:

![The App Workspace listing all apps installed on a tenant](/_fern-files/_img/8400348727e23b5c82580a4b14b3f1daabb62e5f242371d4a7e0ff63cb83c251.webp)

An app that appears in the App Workspace is the app's **installation**.

This distinction also matters when interacting with apps programmatically. Legacy apps only
have an `app_id`, which covers both the definition and the installation. Non-legacy apps
have both an `app_definition` and an `app_id`, where the `app_id` refers to the app
installation.

## App credentials

Credentials for legacy apps look and work differently from new app credentials.

![A legacy app's credentials section showing a long client ID](/_fern-files/_img/641698e75bcf78d72bec092a0c982429c30d3af451b13350735389ecf3e2f7fd.webp)

Legacy app credentials are generated per tenant and cannot be used to generate tokens for
any other tenant.

The client ID for new apps is shorter, and the ID and secret can generate a valid token for
any installing tenant, including the home tenant.

![A non-legacy app's credentials section showing a shorter client ID](/_fern-files/_img/45647149b96adfe17f81c624b9c2e1cbbb6e708c29baa299543469335a7ba58c.webp)

## App versions

[App versioning](/docs/managing-and-sharing-benchling-apps#app-versioning) is not available
for legacy apps. There is no "Version History" tab for them.

Legacy apps can still be updated via the
[legacy manifest APIs](/docs/api/v2-beta/benchling-api-beta/apps/put-benchling-app-manifest).
Uploading a new manifest for a specific app via the API updates that app on the home tenant
immediately. These updates are logged in audits, but version information is not available
for them.

If a legacy app's manifest was shared with another tenant at any time, updating the
manifest on one tenant does not affect installations on other tenants.

## App sharing

Legacy apps do not have access to the
[Share feature](/docs/managing-and-sharing-benchling-apps#sharing-an-app). The only way to
share a legacy app is to provide a copy of the manifest to the installing tenant, then ask
them to share their app credentials with the developer, securely.

## Webhook verification

Legacy apps using the [Webhooks feature](/docs/getting-started-with-webhooks) must use a
different JWKS URL to
[verify webhooks coming from Benchling](/docs/webhook-verification). For legacy apps, use
`https://benchling.com/apps/jwks/{app_installation_id}`.