---
title: "Bitbucket Cloud"
canonical_url: "https://docs.getdx.com/connectors/bitbucket-cloud/"
md_url: "https://docs.getdx.com/connectors/bitbucket-cloud.md"
last_updated: "2026-05-15"
---

# Bitbucket Cloud
By integrating Bitbucket Cloud with DX, you can analyze pull requests, and repositories data. Please refer to the API documentation below and our [schema explorer](https://docs.getdx.com/schema/) to see what data DX imports—note that DX does not read or access your source code.

In addition to the Bitbucket Cloud connector, you can set up additional connectors for [Bitbucket Pipelines](https://docs.getdx.com/connectors/bitbucket-pipelines/). Each Bitbucket-related connection in DX should utilize a separate Workspace Access Token or API token to avoid rate limit issues.

## Prerequisites

To connect Bitbucket Cloud to DX, you need:

- a [Workspace Access Token](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/)
- if you cannot create a Workspace Access Token, create an [API Token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/) instead

## Setup instructions


> This connector supports multiple credentials. You can add additional credentials to distribute API requests across multiple tokens, improving import speed and reliability. To learn more, go to [Can I use multiple API credentials for a data connector?](https://docs.getdx.com/knowledgebase/can-i-use-multiple-api-credentials-for-a-data-connector/)


Follow the steps below to connect Bitbucket Cloud to DX.

### Data connection

#### Step 1

Before setting up a connection for Bitbucket, first set up a [Jira connection](https://docs.getdx.com/connectors/jira-cloud/)—this is required for DX to identify Bitbucket users.

#### Step 2

1. If using a [Workspace Access Token](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/), create a token for DX that includes the following scopes:
   - account
   - pipeline
   - pullrequest
   - repository
2. Or, if using an [API Token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/), create a token for DX that includes the following scopes:
   - `read:repository:bitbucket`
   - `read:pullrequest:bitbucket`
   - `read:pipeline:bitbucket`
   - `read:workspace:bitbucket`

#### Step 3

- Navigate to the connections page in DX and select "+ Connection" in the top right.
- Enter the credentials you have generated in the previous steps—refer to the information below for errors and troubleshooting.
  - If using a [Workspace Access Token](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/), select the `API token` authentication method
  - If using an [API Token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/), select the `Basic auth` authentication method
- Please note that your workspace name should be first path in the URL, i.e., if your workspace URL is `https://bitbucket.org/myworkspace/`, your workspace name is `myworkspace`.

### Webhooks

DX supports Bitbucket webhooks ingestion to sync pull request data in real-time. This is recommended in order to ensure real-time data accuracy in DX.

You can enable webhooks via the Bitbucket API using a curl command like below.

```
curl --location 'https://api.bitbucket.org/2.0/workspaces/get-dx/hooks' \
--header 'Authorization: <AUTHORIZATION>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
      "description": "",
      "url": "<URL>",
      "active": true,
      "secret": "<SECRET>",
      "events": [
        "pullrequest:created",
        "pullrequest:fulfilled",
        "pullrequest:rejected",
        "pullrequest:unapproved",
        "pullrequest:updated"
      ]
    }'
```

To set the value for the `<AUTHORIZATION>` placeholder:

- if using a Workspace Access Token, replace it with `Bearer <access_token>`
- if using an API Token, replace it with `Basic <Base64_encoded atlassian_account_email:api_token>`

To set the value for the `<URL>` placeholder, enter https://yourinstance.getdx.net/webhooks/bitbucket but uwith your unique subdomain.

To set the value for the `<SECRET>` placeholder, enter your webhooks secret from DX. This can be found on the Connections admin page in DX.

Here's a full example:

```
curl --location 'https://api.bitbucket.org/2.0/workspaces/get-dx/hooks' \
--header 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
      "description": "DX bitbucket cloud webhook setup",
      "url": "https://test.getdx.net/webhooks/bitbucket",
      "active": true,
      "secret": "a-very-secret-string",
      "events": [
        "pullrequest:created",
        "pullrequest:fulfilled",
        "pullrequest:rejected",
        "pullrequest:unapproved",
        "pullrequest:updated"
      ]
    }'
```

## API reference

The table below lists the specific API endpoints that are used by DX.


| Endpoint | Documentation |
|--------------------------------------------------------------------------------------------------|---------------|
| /repositories/{workspace_name} | [Link](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/#api-repositories-workspace-get) |
| /repositories/{workspace_name}/{repo}/pullrequests | [Link](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/#api-repositories-workspace-repo-slug-pullrequests-get) |
| /repositories/{workspace_name}/{repo}/pullrequests/{id}/activity | [Link](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/#api-repositories-workspace-repo-slug-pullrequests-activity-get) |
| /repositories/{workspace_name}/{repo}/pipelines | [Link](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines/#api-repositories-workspace-repo-slug-pipelines-get) |
| /workspaces/{workspace_name}/members | [Link](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-workspaces/#api-workspaces-workspace-members-get) |
| /repositories/{workspace_name}/{repo}/commit/{sha} | [Link](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-commits/#api-repositories-workspace-repo-slug-commit-commit-get) |
| repositories/{workspace_name}/{repo}/pullrequests/{id}/comments | [Link](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/#api-repositories-workspace-repo-slug-pullrequests-pull-request-id-comments-get) |


## Errors

The table below lists potential error codes when adding a connection in DX.


| Error | Description |
|------------------------|--------------------------------------------------------------------------|
| `invalid_credentials` | Your API credentials entered are not valid. |
| `invalid_permissions` | Your API token does not have the permissions required by DX. |
| `no_resources` | DX cannot access any projects or repositories. |


## Curl commands

#### When connection verification fails

When DX verifies a Bitbucket Cloud connection, it checks access to workspace repositories. If your connection is failing, you can test these endpoints directly using the curl commands below to troubleshoot the issue.

<div>
  <p class="mb-4 text-sm text-gray-700">Replace YOUR_WORKSPACE_NAME and authentication credentials with your actual values before running these commands.</p>
  
  <div class="mb-4 p-3 bg-gray-50 rounded">
    <p class="font-medium text-sm mb-2">Choose your authentication method:</p>
    <p class="text-sm"><strong>Workspace Access Token:</strong> Use <code>-H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN'</code></p>
    <p class="text-sm"><strong>API Token:</strong> Use <code>-u ATLASSIAN_ACCOUNT_EMAIL:API_TOKEN</code></p>
  </div>

  <h4>1. Test Workspace Repositories Access</h4>
  <p>This verifies that your credentials can access repositories in your workspace:</p>
  
  <p class="text-sm font-medium mb-2">With Workspace Access Token:</p>
  <div class="code-block-wrapper">
    <button class="copy-button" title="Copy to clipboard">
      <svg class="copy-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>
      <svg class="check-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>
    </button>
    <pre><code class="language-bash">curl -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN' -H 'Accept: application/json' 'https://api.bitbucket.org/2.0/repositories/YOUR_WORKSPACE_NAME'</code></pre>
  </div>
  
  <p class="text-sm font-medium mb-2 mt-4">With API Token:</p>
  <div class="code-block-wrapper">
    <button class="copy-button" title="Copy to clipboard">
      <svg class="copy-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>
      <svg class="check-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>
    </button>
    <pre><code class="language-bash">curl -u ATLASSIAN_ACCOUNT_EMAIL:API_TOKEN -H 'Accept: application/json' 'https://api.bitbucket.org/2.0/repositories/YOUR_WORKSPACE_NAME'</code></pre>
  </div>

  <h4>2. Test Workspace Members Access</h4>
  <p>This verifies that your credentials can access workspace members:</p>
  
  <p class="text-sm font-medium mb-2">With Workspace Access Token:</p>
  <div class="code-block-wrapper">
    <button class="copy-button" title="Copy to clipboard">
      <svg class="copy-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>
      <svg class="check-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>
    </button>
    <pre><code class="language-bash">curl -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN' -H 'Accept: application/json' 'https://api.bitbucket.org/2.0/workspaces/YOUR_WORKSPACE_NAME/members'</code></pre>
  </div>
  
  <p class="text-sm font-medium mb-2 mt-4">With API Token:</p>
  <div class="code-block-wrapper">
    <button class="copy-button" title="Copy to clipboard">
      <svg class="copy-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>
      <svg class="check-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>
    </button>
    <pre><code class="language-bash">curl -u ATLASSIAN_ACCOUNT_EMAIL:API_TOKEN -H 'Accept: application/json' 'https://api.bitbucket.org/2.0/workspaces/YOUR_WORKSPACE_NAME/members'</code></pre>
  </div>
</div>

If you receive a 401 Unauthorized error, your credentials are invalid. If you receive a 403 Forbidden error, your token doesn't have the required permissions. If you receive a 404 Not Found error or empty results, check that your workspace name is correct.

**Note about Authentication**: The `-u ATLASSIAN_ACCOUNT_EMAIL:API_TOKEN` flag uses curl's built-in basic authentication, which automatically handles the Base64 encoding required for Bitbucket authentication. For workspace access tokens, use the Bearer token format as shown above.

## Data Cloud API

Once the initial connection is created successfully, Bitbucket Cloud credentials can be managed via the Data Cloud API.

- [credentials.create](https://docs.getdx.com/datacloudapi/methods/credentials.create/)
- [credentials.update](https://docs.getdx.com/datacloudapi/methods/credentials.update/)
- [credentials.info](https://docs.getdx.com/datacloudapi/methods/credentials.info/)
- [credentials.list](https://docs.getdx.com/datacloudapi/methods/credentials.list/)
- [credentials.delete](https://docs.getdx.com/datacloudapi/methods/credentials.delete/)

### Credential fields

Bitbucket Cloud supports two authentication methods. Use either a workspace access token **or** a username and app password — not both.


| Field | Type | Description |
| ----- | ---- | ----------- |
| `secrets.api_token` | `String` | A Bitbucket workspace access token. Use this **or** `username` + `password`. |
| `settings.username` | `String` | Atlassian account email. Required when using an app password. |
| `secrets.password` | `String` | A Bitbucket app password. Use together with `username`. |


**With workspace access token:**

```json
{
  "id": 456,
  "secrets": {
    "api_token": "ATBBfakeWorkspaceAccessToken000000000000123abc"
  }
}
```

**With username and app password:**

```json
{
  "id": 456,
  "settings": {
    "username": "dx-automation@myfakecompany.com"
  },
  "secrets": {
    "password": "fake-app-password-here"
  }
}
```
---

## Sitemap

[Overview of all docs pages](/llms.txt)