BitBucket Integration - API Token (recommended)

Integrate BitBucket using API Token

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, 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.

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

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.

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

2. Select Bitbucket as the app and click next.

3. 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

1. 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!