Authentication

The plugin requires authentication to access the Bitbucket API. The available methods depend on whether you are connecting to Bitbucket Cloud or Bitbucket Data Center.

OAuth2 (Cloud)

1. When prompted to authenticate, your default browser opens a Bitbucket authorization page.
2. Log in to your Bitbucket account (if not already logged in) and grant access to the plugin.
3. After you grant access, the plugin captures the response through a local callback and stores your credentials automatically. You can then close the browser tab and return to the IDE.

The plugin automatically refreshes your OAuth2 token in the background. If the refresh fails, you will be prompted to re-authenticate.

Completing Authorization Manually

If the local callback cannot be reached (for example, it is blocked by a firewall, or you are signing in on a different machine), select Retrieve Auth Code Manually when prompted. The plugin then guides you through the following steps:

1. The authorization link is copied to your clipboard. Paste it into any browser.
2. Sign in and authorize the plugin.
3. The browser redirects to a localhost page that shows an error — this is expected.
4. Copy the entire URL from the browser's address bar and paste it back into the plugin.

API Tokens (Cloud)

The plugin does not support authenticating to Bitbucket Cloud with API tokens — Atlassian's replacement for app passwords, which are being retired. This is caused by limitations in Atlassian's Bitbucket Cloud API rather than a restriction in the plugin. Use OAuth2 to connect to Bitbucket Cloud instead.

note

We are tracking this limitation and can add API token support once Atlassian resolves the underlying API gaps. Please vote for the blocking issues on Atlassian's issue tracker and leave a comment describing your use case to help raise their priority:

• BCLOUD-20926
• BCLOUD-21086
• BCLOUD-23331
• BCLOUD-23904
• BCLOUD-23906
• BCLOUD-23907
• BCLOUD-23909
• BCLOUD-23911
• BCLOUD-23912
• BCLOUD-23913

Username and Password (Data Center)

Enter your Bitbucket Data Center username and password when prompted.

HTTP Access Token (Data Center)

1. In Bitbucket Data Center, go to your Profile → Manage Account → HTTP access tokens.
2. Click Create token, give it a name, and grant it Repository write permission.
3. Copy the generated token.
4. When the plugin prompts for authentication, select HTTP Access Token and paste the token.

Changing Account

To switch to a different Bitbucket account or change the authentication method, use the Change Account action in the Bitbucket Pull Requests tool window toolbar.

Default Account

When logging in, you can check Use this account for other projects by default. This makes the current credentials the default for any new project that connects to the same Bitbucket instance.

Credential Storage

All credentials are stored securely in the IDE's built-in credential store (Settings | Appearance & Behavior | System Settings | Passwords). No passwords or tokens are stored in plain text or in project files.