App versioning lets you safely add, change, test, or remove functionality in your app without disrupting existing users. You can manage app versions through the Developer Center, enabling seamless transitions between versions and ensuring stability for your users.

Versioning follows a clear lifecycle: draft > live > deprecated. A version starts in draft, where you can make changes and test it. Once it's ready, you can gradually release it or directly promote it to live, making it visible to all users. When a new live (production) version is released, the old version becomes deprecated, so it will remain accessible to users but will no longer receive updates.

Version statuses

You can make all changes (e.g., updating permissions, adding or deprecating a feature, fixing a bug, etc.) in one type of app version, so you don't need to worry about major and minor versioning. However, we support a handful of different version statuses for you to draft, test, publish, and remove versions.

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 Manage tab and click App versions.
3. Create a new draft version. You can skip this step if you already have one.
4. Under the Build tab, click Features and locate the app feature you'd like to deprecate.
5. Click the three dots next to the app feature and select Deprecate feature.
6. Check the box on the pop-up, and input a deprecation date.
7. Click Save. Once the new version is promoted to live, users will see in-app banners alerting them of the deprecation.
8. 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 Manage tab and click App versions.
3. Create a new draft version. You can skip this step if you already have one.
4. Under the Build tab, click Features and locate the app feature you'd like to delete.
5. 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 any failed API requests when required permissions haven’t been granted. This means preparing for situations where users may not approve updates immediately, so certain features might not work as expected until they do.

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”]
}

How to manage app versions

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 from two different places:

1. Under Manage in the left-side menu, open the App Versions tab and click New version.
2. Click the New version button under your app's name. This button only appears if you don't have a Draft version.

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.

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 if you have a draft version.

Note that most changes will be implemented automatically after promoting a version to live, 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.

Gradually release a version

You can gradually release new features to your users by following these steps:

1. Under Manage in the left-side menu, open the App Versions tab.
2. Click Gradual Release.
3. Select a version for gradual release.
4. Click Select.
5. Specify which features, accounts, and regions to release the version to.
6. Click Release in the top-right corner.

Delete a draft version

After creating multiple app versions, the app version list can easily become cluttered, so you can delete draft versions to keep your app organized. To ensure continuity for your users, only draft versions can be deleted, not live or deprecated versions.

1. Under Manage in the left-side menu, open the App Versions tab.
2. Locate the version you want to delete and click the three-dots on the far right.
3. Select Delete this version.
4. Click Delete.

Supporting past/deprecated versions

New app versions are automatically pushed to users, but 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.

When a live version is replaced, the original version becomes deprecated. Developers are required to continue supporting deprecated versions to ensure users who haven’t upgraded yet still have access to required features. Deprecated versions remain functional, but they are not recommended for new users and will no longer receive updates.

Over time, you can encourage users to move to the latest version, but support for deprecated versions must be maintained until all users have migrated. 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.