update from Bitbucket private repositories: HTTP 401 errors since end of February 2026 (possible OAuth 1 → OAuth 2 change)

[garubi]

Hello,

I have been using plugin-update-checker for several years to distribute updates for private plugins hosted on Bitbucket Cloud repositories.

The setup has been stable for years, but starting recently (around early March 2026) all update checks against Bitbucket private repositories started failing with HTTP 401 errors.

Nothing has changed in my plugins or configuration.

Environment

• WordPress: 6.9.4
• plugin-update-checker: latest version from this repository
• Hosting: standard PHP hosting
• Repository provider: Bitbucket Cloud (private repositories)

Code used

I use the Bitbucket integration with OAuth consumer credentials as described in the documentation:

add_action( 'plugins_loaded', 'pandplan_autoload_library', 0 );
function pandplan_autoload_library(){

   $myUpdateChecker = PucFactory::buildUpdateChecker(
       'https://bitbucket.org/ottomedia/pandora-planning/',
       __FILE__,
       'pandora-planning'
   );

   $myUpdateChecker->setAuthentication(array(
       'consumer_key' => 'XXXX',
       'consumer_secret' => 'YYYY',
   ));
}

This configuration has worked reliably for years.

Errors ### returned

When checking for updates from the WordPress dashboard, I now get:

BitBucket API error. Base URL: "https://api.bitbucket.org/2.0/repositories/ottomedia/pandora-fattureincloud/src/master/readme.txt", HTTP status code: 401.

BitBucket API error. Base URL: "https://api.bitbucket.org/2.0/repositories/ottomedia/pandora-fattureincloud/refs/tags?sort=-target.date", HTTP status code: 401.

BitBucket API error. Base URL: "https://api.bitbucket.org/2.0/repositories/ottomedia/pandora-fattureincloud/refs/branches/master", HTTP status code: 401.

Could not retrieve version information from the repository.

The problem affects all my plugins hosted on Bitbucket private repositories.

Possible cause

My suspicion is that this is related to Bitbucket Cloud authentication changes.

Bitbucket has recently deprecated OAuth 1.0 / legacy authentication and is transitioning to OAuth 2 and access tokens (brownout period started late February 2026).
Reference:
https://developer.atlassian.com/cloud/bitbucket/changelog/
Since plugin-update-checker currently authenticates to Bitbucket using:

consumer_key
consumer_secret

it may rely on the old OAuth flow that Bitbucket is deprecating.

Questions

Are there plans to update the Bitbucket integration to support the new authentication model?

I would be happy to help test any fixes if needed.

Thanks for maintaining this library — it has been extremely useful for distributing private plugin updates.

[mcchoma]

I am facing same issues since Bitbucket began rolling brownouts of OAuth1 late February. OAuth1 will be completely blacked out and unsupported on Saturday. This is indeed an issue that renders updating from Bitbucket repos impossible after Saturday March 14, 2026. I've been advised to either self-host an updates repo or switch to Github.

https://community.developer.atlassian.com/t/deprecation-notice-oauth-1-0-and-implicit-grant-flows-for-bitbucket-cloud/97520

Essentially, a fix for updating via Bitbucket likely isn't coming any time soon and any plugin or theme using Bitbucket for updates will be dead on Saturday. Manual intervention will be necessary to change the update mechanism. Personally, I'm done with Bitbucket. This information was poorly announced and considering their increasingly frequent outages, tanking stock price, and having just laid off 1,600 employees in favor of AI the future of Atlassian is not looking good.

[littlbr]

Hi,

Can we know if there is any plan to support OAuth2 with Bitbucket in the pipeline?
If not, would you be willing to consider a pull request if someone in our team worked on a solution?

Many thanks for the lib, which is an essential piece of our workflow.

[cristianozanca]

Hi all, solved and tested, it works!

brief:

Since September 9, 2025, Bitbucket has deprecated app passwords and replaced them
with API tokens. The new authentication method requires email + API token as Basic Auth,
but PUC only supports OAuth consumer key/secret via OAuthSignature.

All API calls return HTTP 401 when using the new Bitbucket API tokens.

How to generate a Bitbucket API token

1. Log in to bitbucket.org
2. Click on your profile avatar → Personal settings
3. Under Security section, click API tokens
4. Click Create API token with scope
5. Give it a name (e.g. plugin-update-checker)
6. Set expiration date as needed
7. Under Apps select Bitbucket
8. Under Select Bitbucket scopes select read:repository:bitbucket (View your repositories)
9. Click Create and copy the token immediately (it will only be shown once)

To authenticate with Bitbucket APIs you need:

• Your Bitbucket email address as username
• The API token as password

Verify the token works with curl

curl -u "your@email.com:YOUR_API_TOKEN" \
  "https://api.bitbucket.org/2.0/repositories/username/repository-name"

Root cause

In Puc/v5p6/Vcs/BitBucketApi.php, the setAuthentication method only handles
OAuth credentials and ignores email+token combinations.

Proposed fix

In setAuthentication, detect if consumer_key contains @ (email address) and
use Basic Auth instead of OAuth.

Add a $basicAuth property:
private $basicAuth = null;

Modify setAuthentication:
if ( strpos($credentials['consumer_key'], '@') !== false ) {
$this->basicAuth = base64_encode(
$credentials['consumer_key'] . ':' . $credentials['consumer_secret']
);
$this->oauth = null;
} else {
$this->oauth = new OAuthSignature(...);
$this->basicAuth = null;
}

Add the Authorization header in the api method:
if ( $this->basicAuth ) {
$options['headers'] = array(
'Authorization' => 'Basic ' . $this->basicAuth,
);
}

Usage in plugin code

$myUpdateChecker->setAuthentication(array(
'consumer_key' => 'your@email.com', // Bitbucket email
'consumer_secret' => 'YOUR_API_TOKEN', // Bitbucket API token
));

References

• Bitbucket app passwords deprecation: https://support.atlassian.com/bitbucket-cloud/docs/using-access-tokens/
• App passwords end of life: June 9, 2026

this is the new code in the file BitBucketApi.php:

######################################################

`<?php

namespace YahnisElsts\PluginUpdateChecker\v5p6\Vcs;

use YahnisElsts\PluginUpdateChecker\v5p6\OAuthSignature;
use YahnisElsts\PluginUpdateChecker\v5p6\Utils;

if ( !class_exists(BitBucketApi::class, false) ):

class BitBucketApi extends Api {
	/**
	 * @var OAuthSignature
	 */
	private $oauth = null;

	/**
	 * @var string
	 */
	private $username;

	/**
	 * @var string
	 */
	private $repository;

	################################################# NEW

	private $basicAuth = null; // <-- added raw

	################################################# end NEW

	public function __construct($repositoryUrl, $credentials = array()) {
		$path = wp_parse_url($repositoryUrl, PHP_URL_PATH);
		if ( preg_match('@^/?(?P<username>[^/]+?)/(?P<repository>[^/#?&]+?)/?$@', $path, $matches) ) {
			$this->username = $matches['username'];
			$this->repository = $matches['repository'];
		} else {
			throw new \InvalidArgumentException('Invalid BitBucket repository URL: "' . $repositoryUrl . '"');
		}

		parent::__construct($repositoryUrl, $credentials);
	}

	protected function getUpdateDetectionStrategies($configBranch) {
		$strategies = array(
			self::STRATEGY_STABLE_TAG => function () use ($configBranch) {
				return $this->getStableTag($configBranch);
			},
		);

		if ( ($configBranch === 'master' || $configBranch === 'main') ) {
			$strategies[self::STRATEGY_LATEST_TAG] = array($this, 'getLatestTag');
		}

		$strategies[self::STRATEGY_BRANCH] = function () use ($configBranch) {
			return $this->getBranch($configBranch);
		};
		return $strategies;
	}

	public function getBranch($branchName) {
		$branch = $this->api('/refs/branches/' . $branchName);
		if ( is_wp_error($branch) || empty($branch) ) {
			return null;
		}

		//The "/src/{stuff}/{path}" endpoint doesn't seem to handle branch names that contain slashes.
		//If we don't encode the slash, we get a 404. If we encode it as "%2F", we get a 401.
		//To avoid issues, if the branch name is not URL-safe, let's use the commit hash instead.
		$ref = $branch->name;
		if ((urlencode($ref) !== $ref) && isset($branch->target->hash)) {
			$ref = $branch->target->hash;
		}

		return new Reference(array(
			'name' => $ref,
			'updated' => $branch->target->date,
			'downloadUrl' => $this->getDownloadUrl($branch->name),
		));
	}

	/**
	 * Get a specific tag.
	 *
	 * @param string $tagName
	 * @return Reference|null
	 */
	public function getTag($tagName) {
		$tag = $this->api('/refs/tags/' . $tagName);
		if ( is_wp_error($tag) || empty($tag) ) {
			return null;
		}

		return new Reference(array(
			'name' => $tag->name,
			'version' => ltrim($tag->name, 'v'),
			'updated' => $tag->target->date,
			'downloadUrl' => $this->getDownloadUrl($tag->name),
		));
	}

	/**
	 * Get the tag that looks like the highest version number.
	 *
	 * @return Reference|null
	 */
	public function getLatestTag() {
		$tags = $this->api('/refs/tags?sort=-target.date');
		if ( !isset($tags, $tags->values) || !is_array($tags->values) ) {
			return null;
		}

		//Filter and sort the list of tags.
		$versionTags = $this->sortTagsByVersion($tags->values);

		//Return the first result.
		if ( !empty($versionTags) ) {
			$tag = $versionTags[0];
			return new Reference(array(
				'name' => $tag->name,
				'version' => ltrim($tag->name, 'v'),
				'updated' => $tag->target->date,
				'downloadUrl' => $this->getDownloadUrl($tag->name),
			));
		}
		return null;
	}

	/**
	 * Get the tag/ref specified by the "Stable tag" header in the readme.txt of a given branch.
	 *
	 * @param string $branch
	 * @return null|Reference
	 */
	protected function getStableTag($branch) {
		$remoteReadme = $this->getRemoteReadme($branch);
		if ( !empty($remoteReadme['stable_tag']) ) {
			$tag = $remoteReadme['stable_tag'];

			//You can explicitly opt out of using tags by setting "Stable tag" to
			//"trunk" or the name of the current branch.
			if ( ($tag === $branch) || ($tag === 'trunk') ) {
				return $this->getBranch($branch);
			}

			return $this->getTag($tag);
		}

		return null;
	}

	/**
	 * @param string $ref
	 * @return string
	 */
	protected function getDownloadUrl($ref) {
		return sprintf(
			'https://bitbucket.org/%s/%s/get/%s.zip',
			$this->username,
			$this->repository,
			$ref
		);
	}

	/**
	 * Get the contents of a file from a specific branch or tag.
	 *
	 * @param string $path File name.
	 * @param string $ref
	 * @return null|string Either the contents of the file, or null if the file doesn't exist or there's an error.
	 */
	public function getRemoteFile($path, $ref = 'master') {
		$response = $this->api('src/' . $ref . '/' . ltrim($path));
		if ( is_wp_error($response) || !is_string($response) ) {
			return null;
		}
		return $response;
	}

	/**
	 * Get the timestamp of the latest commit that changed the specified branch or tag.
	 *
	 * @param string $ref Reference name (e.g. branch or tag).
	 * @return string|null
	 */
	public function getLatestCommitTime($ref) {
		$response = $this->api('commits/' . $ref);
		if ( isset($response->values, $response->values[0], $response->values[0]->date) ) {
			return $response->values[0]->date;
		}
		return null;
	}

	/**
	 * Perform a BitBucket API 2.0 request.
	 *
	 * @param string $url
	 * @param string $version
	 * @return mixed|\WP_Error
	 */
	public function api($url, $version = '2.0') {
		$url = ltrim($url, '/');
		$isSrcResource = Utils::startsWith($url, 'src/');

		$url = implode('/', array(
			'https://api.bitbucket.org',
			$version,
			'repositories',
			$this->username,
			$this->repository,
			$url
		));
		$baseUrl = $url;

		if ( $this->oauth ) {
			$url = $this->oauth->sign($url,'GET');
		}

		$options = array('timeout' => wp_doing_cron() ? 10 : 3);

############################################## NEW

if ( $this->basicAuth ) {
$options['headers'] = array(
'Authorization' => 'Basic ' . $this->basicAuth,
);
}

if ( !empty($this->httpFilterName) ) {
$options = apply_filters($this->httpFilterName, $options);
}

############################################# end NEW

		if ( !empty($this->httpFilterName) ) {
			$options = apply_filters($this->httpFilterName, $options);
		}
		$response = wp_remote_get($url, $options);
		if ( is_wp_error($response) ) {
			do_action('puc_api_error', $response, null, $url, $this->slug);
			return $response;
		}

		$code = wp_remote_retrieve_response_code($response);
		$body = wp_remote_retrieve_body($response);
		if ( $code === 200 ) {
			if ( $isSrcResource ) {
				//Most responses are JSON-encoded, but src resources just
				//return raw file contents.
				$document = $body;
			} else {
				$document = json_decode($body);
			}
			return $document;
		}

		$error = new \WP_Error(
			'puc-bitbucket-http-error',
			sprintf('BitBucket API error. Base URL: "%s",  HTTP status code: %d.', $baseUrl, $code)
		);
		do_action('puc_api_error', $error, $response, $url, $this->slug);

		return $error;
	}

	/**
	 * @param array $credentials
	 */

############################################################ UPDATED

public function setAuthentication($credentials) {
parent::setAuthentication($credentials);

if ( !empty($credentials) && !empty($credentials['consumer_key']) ) {
    // Controlla se è email+token (contiene @) oppure OAuth
    if ( strpos($credentials['consumer_key'], '@') !== false ) {
        // Email + API token → Basic Auth
        $this->basicAuth = base64_encode($credentials['consumer_key'] . ':' . $credentials['consumer_secret']);
        $this->oauth = null;
    } else {
        // OAuth consumer key/secret
        $this->oauth = new OAuthSignature(
            $credentials['consumer_key'],
            $credentials['consumer_secret']
        );
        $this->basicAuth = null;
    }
} else {
    $this->oauth = null;
    $this->basicAuth = null;
}

}

########################################################### end UPDATED

	/*
	public function setAuthentication($credentials) {
		parent::setAuthentication($credentials);

		if ( !empty($credentials) && !empty($credentials['consumer_key']) ) {
			$this->oauth = new OAuthSignature(
				$credentials['consumer_key'],
				$credentials['consumer_secret']
			);
		} else {
			$this->oauth = null;
		}
	}

	*/

	public function signDownloadUrl($url) {
		//Add authentication data to download URLs. Since OAuth signatures incorporate
		//timestamps, we have to do this immediately before inserting the update. Otherwise,
		//authentication could fail due to a stale timestamp.
		if ( $this->oauth ) {
			$url = $this->oauth->sign($url);
		}
		return $url;
	}
}

endif;
`

[YahnisElsts]

I don't use Bitbucket much myself, so this hasn't been a priority, but I looked into the issue over the last few days. Try the feat-bitbucket-api-token branch (or see eceb677). The basic implementation is similar to what @cristianozanca proposed above, but I extended it to also add the required Authorization header to update downloads. And since Bitbucket and GitHub integrations now both use basic auth, I also did some refactoring there.

[PavelVybiral]

Hi all,
@YahnisElsts , thank you! I've tested the feat-bitbucket-api-token branch and I can confirm it works for me for plugins and also for themes.

If no problems will be found, when can this feature be merged into master, so we can use it via Composer, please?

Thank you @YahnisElsts and @cristianozanca for your work. I really appreciate it. :)

[YahnisElsts]

Ideally, I'd like to see a bit more testing. But if no one shows up to object to this implementation, I could probably merge it sometime next week.

[garubi]

I'll try to find a slot monday to test it, but I'm not sure I'll can...

[PavelVybiral]

Hi all,
are there any updates about this issue, please?

[YahnisElsts]

Oops, this slipped my mind. I guess I'll merge it now.