Last updated Oct 28, 2024

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.

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.

Button placement and trust

When users click your install button, the next page that appears requests access permissions to their Bitbucket account. It's best practice to 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

For registered apps, the href of the button or link must be in the following format:

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

For unregistered apps, the link must be in the following format:

1
2
https://bitbucket.org/site/addons/authorize?descriptor_uri=<descriptor_uri>&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:
- an addon_key which specifies the key of your app. (For registered apps)
- a descriptor_uri that points to your app's descriptor. (For unregistered 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.
The redirect_uri may be omitted, in which case the user is redirected back to Bitbucket by default.

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.

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

For production environments, we recommend bundling these CSS files with your site, rather than relying on a third-party CDN.

1
2
<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>

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:

Error	Description
`access_denied`	The user has opted not to grant the app access to their account.
`invalid_descriptor`	The descriptor found at `descriptor_uri` is invalid.
`invalid_request`	The 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_error`	Something 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.

Registered apps will also have a jwt query parameter added to the redirect_uri. This should be used to validate the request using the shared secret you received when registering your app. See Exposing a service for detailed instructions on how to use this parameter.