Bitbucket API tokens and the username that causes a 401

Tuesday's agent could list commits. Wednesday it gets 401 on the same repository. The token in the store is new. The request still authenticates with the Bitbucket username, because that is what the old app-password snippet did. API tokens do not want that username. They want the Atlassian account email. The 401 is an identity mismatch, and the repository never saw a valid call.

This post is the Bitbucket Cloud credential change: which username goes with which secret, how far a scoped token reaches, and the dates Atlassian published for killing app passwords.

The username depends on the secret

Atlassian's note on 401s draws the line. App passwords authenticate with the Bitbucket username from account settings. The Atlassian email does not work with an app password, and neither does the password's label. The account password does not work either.

API tokens reverse the pair. Basic auth on the REST API uses the Atlassian account email as the username and the API token as the password. The Bitbucket username does not work in that pair, and the token's name does not work. A token with no scopes does not work. Bearer auth with the token is also documented.

That single swap is why an agent "upgrade" breaks overnight. The code path still sends username:secret in the shape the app password used. You replaced the secret and left the username. Bitbucket rejects it before any repository permission is considered.

Git over HTTPS has its own examples on the using API tokens page, including the Bitbucket username and the static username x-bitbucket-api-token-auth. Cloning wants the scope read:repository:bitbucket. Pushing also wants write:repository:bitbucket. Atlassian asks you not to leave the token in the remote URL. A model that rewrites git remote to include the token will put it in a file people clone.

The GitHub agent post is a different host and a different token shape. Do not reuse a GitHub fine-grained token pattern here and expect Bitbucket to accept it.

swy search bitbucket
swy get bitbucket
swy list methods

The Bitbucket catalog page is the method list after get. There is no .env file in this project. Swytchcode keeps credentials in its own local store and reads them when a call runs. Connect Bitbucket with swy auth connect. The email and token pair should come from that store, not from a string the model builds.

What the token is allowed to do

API tokens replace app passwords. They are tied to one person. Sharing the token shares everything that token's scopes allow. You cannot view or edit a token after creation. You replace it. You cannot log in to bitbucket.org with it. Atlassian also says these tokens cannot be used to manage workspace actions.

Scopes are chosen at creation. A token without the scope for the endpoint returns a failure that looks like a permissions bug and is actually a minting bug. Read the scope list on the endpoint you enable, and mint the token with those scopes only.

You can limit a token to one workspace. Do that. A token that can see every workspace the human can see is wider than a code agent needs. One workspace, read on the repository for a review bot, write only if the bot is supposed to push. Policy as code should then deny the write methods until that day.

The dates on Atlassian's pages

Creation of app passwords stopped on September 9, 2025. The revoke an app password page says existing app passwords are disabled on June 9, 2026. The 401 article says that from June 9, 2026, API tokens are the only Basic auth for the REST API. A separate Bamboo article has said July 28, 2026. Both of those deadlines are behind you if you are reading this in late 2026. If a 401 remains, assume the caller is still presenting an app password, or presenting an API token with the old username.

Revoke leftover app passwords in Personal settings rather than hoping they already died. A password that still works on a stray client is still a credential.

A 401 checklist that is specific to this host

When the agent gets 401, check these in order. The email on the request is the Atlassian account email, not the Bitbucket username. The secret is an API token, not an app password and not the account password. The token has at least one scope, and that scope matches the endpoint. The token's workspace is the workspace in the URL https://api.bitbucket.org/2.0/repositories/{workspace}/{repository}. A token for workspace acme will not authorize other-team.

None of those checks require a new token with every scope turned on. Widening the token to "make the 401 go away" is how a review bot gains write on every repo in the workspace.

Mint one workspace-scoped token with the read scope. Authenticate the REST call as the Atlassian email plus that token. Add a write scope only in the change that enables the write method.

Related reading

• A security checklist before company data. A repository token is access to source code.
• API compliance for agent integrations. What to record about scopes and who can mint tokens.
• API governance tools for AI agents. How the allowlist stays on read methods.
• Log every API call an agent makes. Where a 401 should show the workspace, not the token.

FAQ

Can I still create a Bitbucket app password?

Atlassian stopped creation on September 9, 2025. Their support pages say existing app passwords were disabled on June 9, 2026, and that API tokens are the Basic auth path from that date. Use an API token with scopes.

Which username do I send with an API token?

For REST Basic auth, the Atlassian account email. The Bitbucket username is the app-password rule, and it does not authenticate an API token. Git examples on Atlassian's token page also show x-bitbucket-api-token-auth as a static username.

Will a token scoped to one workspace see a second workspace?

No. The URL workspace and the token workspace have to match. A 401 or an empty result on the other workspace is the scope working. Mint a second token if a second workspace is actually in the agent's job.

What if the token has no scopes?

It will not call the API. Atlassian says a token without scopes does not work. Check the endpoint's required scopes, revoke the empty token, and create a new one. You cannot edit the old one to add scopes.