Last updatedNov 14, 2019

Change Notice - Changes to external app install links effective 10 January 2020

Summary

Depending on if an app has been registered in the “Develop apps” section of Bitbucket settings, the URL that installs the app may change. Apps that have been registered must use the addon_key URL parameter to identify the app. Apps that have not been registered may continue to use the descriptor_uri URL parameter to identify the app, i.e. no change is necessary.

Apps that need to change can and should start using the addon_key parameter today.

As of 10 January 2020 if a registered app is not using the addon_key URL parameter, the installation page will not be able to install the app.

How to tell if an app has been registered

The easiest way to tell if an app has been registered is to see if it's listed in the “Develop apps” section of your Bitbucket settings.

Another way to tell if an app has been registered is to look at the format of the clientKey from each installation callback.

  • keys that begin with connection: indicate that the app has not been registered and does not need to update
  • keys that begin with ari: indicate that the app has been registered and needs to be updated

To update your installation link, remove the descriptor_uri URL parameter and add the addon_key parameter. The value of the addon_key should be the key defined in the app descriptor. The initial installation screen will behave the same when this change is done correctly.

Examples

A link with descriptor_uri for apps that haven’t been registered:

1
https://bitbucket.org/site/addons/authorize?descriptor_uri=<descriptor_uri>&redirect_uri=<redirect_uri>

A link with addon_key for apps that have been registered:

1
https://bitbucket.org/site/addons/authorize?addon_key=<addon_key>&redirect_uri=<redirect_uri>

Marketplace Installation Will Not Change

There are different ways to install an app on Bitbucket. This change is only applicable to apps that are using a link to install the app from its site. Installing from either the Atlassian or Bitbucket marketplace will not be changing.

As a recap, here are the different places where apps can be installed: