App versioning lets you safely add, change, or remove functionality in your app without disrupting existing users. Our versioning mechanism enables you to create new draft versions to make changes to the app.

Every change (e.g., updating permissions, adding or deprecating a feature, fixing a bug, etc.) can be done in one type of version, so there is no need for major or minor versions.

Once your draft version is ready for release, you can promote it to live and it will automatically push the updates to app users. Most changes will automatically be implemented, but some, like updated scopes or permissions, may require user approval. In these instances, users will maintain access to the app but it may not work properly until the changes are approved. These updates will be communicated through app view and integration store banners to encourage users to accept them.

Managing versions

We currently support just one type of app version that enables you to make changes without disrupting user workflows. In your app's App Versions tab, you can create a new version, promote a draft version to live, or delete a draft version. Note that you must enable Developer Mode to see app versions and add them to your account.

Create a new version

You can create a new version when you need to make changes to your app. The draft version inherits all configurations from your app's current live version (e.g., scopes, OAuth, features, app name, etc.), so you must manually update them if you want to make any changes.

The version number automatically increments based on your app’s highest version number, whether live or draft. If your app's live version is v1, but the highest version in your drafts is v3, the new version number will be v4.

You can create a new version from two different places:

1. Open the App Versions tab > click New version
2. Click the New version button under your app's name (this button only appears if you don't already have a draft version)

Promote a draft version to live

You can also promote a draft version to live from two different locations:

1. Open the App Versions tab > select the three-dots in the Actions column > click Publish
2. Click the Promote to live button under your app's name (this button only appears when you have a draft version)

Delete a draft version

The app version list can easily become cluttered after creating multiple versions, so you can delete draft versions to keep your app organized. To ensure continuity for your users, you cannot delete live or deprecated versions. Follow these quick steps to delete a draft version:

1. In the App versions tab, click the three-dots on the far right
2. Select Delete this version
3. Click Delete

Supporting past versions

Even though new versions are automatically pushed to users, some changes (e.g., permissions and scope changes) require manual approval. As a result, accounts may be using your app with various scopes and permissions. Your app’s backend must support the logic of your old versions to account for this. If your app utilized our versioning mechanism prior to January 2024, you must support the logic of your old major versions.

This could mean having endpoints to support old integration recipes or fallback logic in your app’s code if a particular setting or field doesn’t exist. Generally speaking, you should build your backend to support all previous app versions.

If you decide to fully deprecate an old version, you can send the user notifications or show them a screen prompting them to reinstall the app's newest version.

Versioning capabilities

Create an app feature

Using app versioning, you can always add new app features without disrupting existing app users. Once you've created a new draft app version, follow these steps to add a new app feature!

Remove an app feature

When you create a new version, you have the option to either deprecate (recommended) or delete an app feature. Deprecating a feature allows you to set a deprecation date to alert users of its removal, while deleting it immediately removes it. We recommend deprecating the feature before deleting it to give users time to adjust to the update.

Deprecate a feature (recommended)

Deprecating an app feature enables you to remove it while simultaneously providing users with time to adjust to the updates. You can select a deprecation date that will be communicated to users through in-app banners that alert them of the deprecation. The date is solely used for communication purposes, so you must manually remove the app feature on the deprecation date.

To deprecate an app feature:

1. Open your app in the developer center.
2. Navigate to the App Versions tab and create a new version. If you already have a draft version, skip this step.
3. In the Features tab, locate the app feature you'd like to deprecate.
4. Click the three dots next to the app feature and select Deprecate feature.
5. Check the box on the pop-up, and input a deprecation date.
6. Click Save. Once the new version is promoted to live, users will see in-app banners alerting them of the deprecation.
7. On the deprecation date, you must come back to your app and follow the steps to delete the app feature.

Un-deprecate a feature

If you deprecate an app feature but later change your mind, you can always un-deprecate it.

To un-deprecate an app feature:

1. Follow steps 1-4 above.
2. Uncheck the box to deprecate the feature and click Save.

Delete a feature

Unlike deprecating an app feature, deleting a feature immediately removes it from the version once it is promoted to live. We do not recommend this as users who rely on that feature will be blocked from accessing the app.

If you must delete an app feature, follow these steps:

1. Open your app in the developer center.
2. Navigate to the App Versions tab and create a new version. If you already have a draft version, skip this step.
3. In the Features tab, locate the app feature you'd like to delete.
4. Click the three dots next to the app feature and select Delete feature.

Update permissions or scopes

You can update your app’s permissions or scopes at any time by creating a new version. Once live, the new version is automatically pushed to users; however, changes to scopes or permissions require manual user approval. Users are then notified via an in-app banner highlighting the updated scopes or permissions. The banner includes a call to action prompting them to approve the changes.

Users can continue accessing the app without approving the updates, but some features may not work as expected. Your app must handle failed API requests when required permissions haven’t been granted, as it’s unlikely all users will approve the changes immediately.

For view apps, you can check which permissions a user has approved via the permissions property of your app’s context. If the user is a collaborator on the app, all required scopes will appear as approved — even if the user hasn’t explicitly granted them. This behavior is specific to collaborators and does not reflect general user approval status.

permissions:{
  approvedScopes:[“board:read”],
  requiredScopes:[“board:read”,”board:write”]
}