> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/integrations/version-control/bitbucket-integration/bitbucket-integration-api-token-recommended.md).

# BitBucket Integration - API Token (recommended)

To connect Bitbucket Cloud to Hivel using an Atlassian API token, follow these steps:

**Data Access by Hivel**

* Hivel securely accesses the last 30-90 days of commits and pull requests from active repositories during the initial sync.

**Authorization Mechanism**

* Hivel integrates with Bitbucket Cloud using an **Atlassian API token** together with the **Atlassian account email**.
* You retain full control - access can be revoked at any time by deleting the token in your Atlassian account under **Security → API tokens**.

**Requirements**

* Ensure the token is created from an account with write access to all applicable Bitbucket repositories.

**Best Practice**

* Opt for a service account rather than an individual-linked account.
* Service accounts are typically overseen by the company's admin.

**Quick start:** skip the navigation - [open the API tokens page](https://id.atlassian.com/manage-profile/security/api-tokens), then continue from **Step 3**. If the link doesn't take you there, follow from **Step 1** below.

### **Steps to generate an API Token on BitBucket**

#### **Step 1: Prepare a Service Account**

1. **Log into the Atlassian service account:**
   * Use a dedicated service account that has access to the required Bitbucket repositories for Hivel integration.
   * Avoid using personal accounts to ensure only the intended repositories are accessed.

#### **Step 2: Open API Tokens in Your Atlassian Account**

1. Go to your Atlassian account settings at [id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens).
2. Select **Security**, then **API tokens** (the above link should take you there directly).

#### **Step 3: Create the API Token**

1. Choose Create API token with scopes

![](/files/B4jxGmZ88j0kpudEuRCn)

**NOTE:** make sure it's **Create API token with scopes option and not the plain Create API token** button to the left of it. Tokens created without scopes can't read any Bitbucket data, so the connection to Hivel won’t work.

2. Enter *Hivel* as the token name, and choose the **longest expiry your organization's policy allows.** (You can delete the token manually when the engagement ends.) and click **next**.
3. Select **Bitbucket** as the app and click **next**.
4. Grant the required scopes - copy these five all together and paste them in the search box:

```
read:user:bitbucket 
read:workspace:bitbucket 
read:repository:bitbucket 
read:pullrequest:bitbucket 
Admin:workspace:bitbucket
```

<img src="/files/Nj0q6clw6wN0lyvv3PDQ" alt="" height="361" width="768">

2. Create the token and **copy it immediately**, as you won't be able to view it again.

#### **Step 4: Connect in Hivel**

1. **Copy the generated token** immediately, as you won't be able to view it again.
2. Submit the token to Hivel.

Hivel validates the token instantly -if the email or token is wrong, expired, or missing the required access, Hivel shows a clear message telling you exactly what the problem is. Generate a new token with the correct scopes and reconnect.\
\
That's it, all done!