Getting 401 HTTP error when using Basic authentication with Bitbucket Cloud REST APIs
Platform Notice: Cloud Only - This article only applies to Atlassian apps on the cloud platform.
Summary
This knowledge base article outlines the typical cause of receiving the 401 HTTP error during basic authentication to Bitbucket Cloud REST APIs.
Diagnosis
Using a Bitbucket Cloud REST API endpoint with the format below:
curl -v -u <user>:<password> "https://api.bitbucket.org/2.0/workspaces/workspace_id"The above Curl command resulting the 401 HTTP error:
< HTTP/2 401
< server: envoy
* Authentication problem. Ignoring this.
< www-authenticate: Basic realm="Bitbucket.org HTTP"Cause
A 401 error indicates incorrect credentials.
Solution
Up until June 9th 2026 you can use the Bitbucket username and an app password for authentication with Bitbucket Cloud APIs. If you use this approach (not recommended), then:
Ensure that the parameter
<user>in the API call is replaced with the username of your Bitbucket account, which you can find here: https://bitbucket.org/account/settings/. Your Atlassian account email will not work when using an app password; the app password label cannot be used either.Ensure that the parameter
<password>in the API call is replaced with an app password. The account's password will NOT work.
Please keep in mind that we will disable app password creation on September 9th 2025. The recommended approach is to use API tokens instead.
API tokens
Starting June 9th 2026 API tokens will be the only way to use Basic authentication with Bitbucket Cloud's REST APIs. This method works today as well, and we recommend switching to API tokens. In this case:
Ensure that the parameter
<user>in the API call is replaced with your Atlassian account email address. The Bitbucket username or the token name will NOT work when using API tokens.Ensure that the parameter
<password>in the API call is replaced with an API token for the same account. The token needs to have the appropriate scopes (a token without scopes will not work), depending on which API endpoints it is used with. If you select a certain endpoint from the left sidebar in our API documentation, you'll be able to see the API token scopes required for that endpoint. The account's password will NOT work.
Was this helpful?