Last updatedNov 14, 2019

Install an app from your site or application

One of the big advantages of integrating with Bitbucket Connect is that users have a simple two-click process for installing your app. The first click is either on the Add button in the Bitbucket app directory, or an Install button embedded on a website, or in an application. The second click approves Bitbucket access permissions for your app and completes the installation.

Button placement and trust

When users click your install button, the next page that appears requests access permissions to their Bitbucket account. For this reason, be careful that you place the install button in a location users will be able to trust such as a marketing site, product information site, or company sponsored blog post.

Create your button

The href of the button or link must be of the form:

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

For apps that have been registered, the link must be of the form:

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

The following rules apply to the URI construction:

  • URIs must be absolute.
  • It should have one and only one of the following to identify the app:
    • a descriptor_uri that points to your app's descriptor. (For unregistered apps)
    • an addon_key which specifies the key of your app. (For registered apps)
  • The redirect_uri specifies a URL to redirect the user to after they install the app.
  • The redirect_uri must start with the baseUrl of your app. Both are plain URLs (not URI Templates) and do not support context parameters.

Read this notice if you need more help determining if you should use the addon_key or descriptor_uri parameter.

Create a button using Atlaskit

Atlaskit makes delivering a beautiful button simple.

Connect to Bitbucket button

The button above is just a simple link styled with the Atlaskit reduced UI pack:

1
2
3
4
5
6
7
8
9
10
11
<html>
  <head>
    <link rel="stylesheet" href="https://unpkg.com/@atlaskit/reduced-ui-pack@7.0.0/dist/bundle.css" media="all">
    <link rel="stylesheet" href="https://unpkg.com/@atlaskit/css-reset@1.1.5/dist/bundle.css" media="all">
  </head>
  <body>
    <a href="https://bitbucket.org/site/addons/authorize?descriptor_uri=https://example.com&redirect_uri=https://example.com/welcome">
      <button type="button" class="ak-button ak-button__appearance-primary">Connect to Bitbucket</button>
    </a>
  </body>
</html>

A note about development mode

Until your application is listed in the marketplace, users will have to enable development mode before they are able to install your app.

Post install considerations and error states

If the user accepts the installation, and the app installs successfully, they will be redirected to the redirect_uri with the query parameter clientKey appended. The clientKey is an opaque key that references the app's installation for the user or team that installed the app.

If the user does not accept the installation, or the app installation fails, they will be redirected to the redirect_uri with the query parameters error and error_description appended. At time of writing the known list of error codes are:

ErrorDescription
access_deniedThe user has opted not to grant the app access to their account.
invalid_descriptorThe descriptor found at descriptor_uri is invalid.
invalid_requestThe install URL or parameters were malformed in some way. Common causes are:
  • the descriptor_uri or redirect_uri parameter is missing
  • the redirect_uri does not start with the baseUrl specified in the descriptor
  • the descriptor_uri is not secured by HTTPS
server_errorSomething unexpected went wrong.

Check the error_description parameter passed alongside the error parameter for more information about the specific cause. Your page should be resilient to additional error codes being added in future.