Having trouble switching to API tokens

[Paul James]

We've recently received an email that App Passwords will be going away. We currently make use of them.

I created an API token following the documentation and tried to use it to clone a repository using the same command we normally use with the existing app password and it failed. I then tried creating an API token with scopes giving it every scope for bitbucket and that also failed.

The command we used to use with the app password was:

git clone -b <branch> https://<username>:<app password>@bitbucket.org/<project details>.git

I tried the exact same command with the API token simply replacing the app password with the new API token (which as far as I could make out from the documentation is the correct way to do it).

The error received was as follows:

remote: You may not have access to this repository or it no longer exists in this workspace. If you think this repository exists and you have access, make sure you are authenticated.
fatal: Authentication failed for 'https://bitbucket.org/<project details>'

I suspect its something obvious I'm doing but due to lack of simple documentation I can't work out what we are doing wrong.

[Syahrul]

Hey @Paul James 

It sounds like your local Git configuration might be prioritizing a cached App Password or password over the new API token you are providing in the command.

The Solution:
The most reliable way to use an API token is to use the static username x-bitbucket-api-token-auth. This tells Bitbucket explicitly to treat the password field as an API token.

However, since you confirm it works, your computer is likely "remembering" the old password. You can force Git to show you what it's doing by running:
GIT_CURL_VERBOSE=1 git clone ... (as shown above).

How to clear the old credentials:
If the verbose logs show an authorization conflict, you need to clear your local cache:

• Windows: Open Credential Manager > Windows Credentials and remove any entries for git:https://bitbucket.org.
• macOS: Open Keychain Access, search for bitbucket.org, and delete the existing internet password entry.
• Linux/All: You can run echo "url=https://bitbucket.org" | git credential reject to force Git to forget the stored password."

Hope this helps.

Regards,
Syahrul

[Arkadiusz Wroblewski]

Hello @Paul James 

Hello Paul,

I think the main thing here is that for Git clone/fetch/pull, Bitbucket’s API token docs do not use the same pattern as some of the more general token examples.

For Git, I would try either your Bitbucket username or the fixed username x-bitbucket-api-token-auth together with the API token. The token also needs at least repository read permission.

https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/

https://support.atlassian.com/bitbucket-cloud/docs/api-token-permissions/

So please test one of these Formats:

git clone https://<bitbucket_username>:<api_token>@bitbucket.org/<workspace>/<repo>.git

git clone https://x-bitbucket-api-token-auth:<api_token>@bitbucket.org/<workspace>/<repo>.git

If that still fails, I would next check whether the token is scoped to the correct workspace.

FYI: app passwords still work for now and are planned to stop working on June 9, 2026, so you still have a bit of time to test the migration properly.

https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation

[Paul James]

The tests I have done so far have been using the first example (though admittedly with the -b flag being passed to clone as well - I just tried without that and get the same error.

I tried both a simple API Token and an API token created with scopes where every bitbucket scope was ticked and neither worked.

I have just tried with the x-bitbucket syntax and the same token has worked so it just looks like the username:token syntax has an issue.

[Arkadiusz Wroblewski]

@Paul James Ye that seems legit.