Authentication

Use OAuth for browser login or an API token for CI and headless hosts.

OAuth (recommended)

bb auth login

In a terminal, choose Log in with a web browser (OAuth). The CLI opens Bitbucket’s authorization page and stores the resulting tokens. Access tokens normally expire after two hours; the CLI refreshes them while the refresh credentials remain valid. If refresh fails, log in again.

Outside an interactive terminal (pipes, CI, agents, --no-input), a bare bb auth login fails with error 1001 instead of opening a browser: set BB_USERNAME and BB_API_TOKEN, or run it yourself in a terminal. If BB_API_TOKEN is set, even to an empty string, login selects API-token auth. Unset it to choose OAuth.

Caution

OAuth requires a browser that can reach http://localhost:19872/callback on the machine running bb. There is no device-code flow. Use an API token on SSH hosts, containers, or CI runners without that browser access.

Using a custom OAuth consumer

Create a consumer under Workspace settings > Apps and features > OAuth consumers. Set the callback to http://localhost:19872/callback and grant at least Account Read, Repositories Read/Admin, and Pull requests Read/Write to cover the scopes the CLI requests. Grant additional permissions for other workflows, then sign in with the consumer’s key and secret:

bb auth login --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

The custom credentials are stored in the config file. Passing the secret as an argument exposes it to process listings and potentially shell history.

The CLI requests account repository repository:admin pullrequest pullrequest:write. These are legacy OAuth names. The consumer’s configured permissions determine the resulting grant: Bitbucket does not narrow a token when fewer scopes are requested. A custom consumer can therefore grant additional scopes. Do not treat the requested list as proof of the built-in consumer’s complete permissions.

API token (for CI/CD and headless environments)

1. Create a Bitbucket API token. Include read:user:bitbucket so login can verify your identity, plus the scopes for your commands.
2. Supply your Atlassian account email and token. The existing option name is --username / -u, but API tokens require the email, not your Bitbucket username. Atlassian documents this requirement.

If your secret manager or CI platform supplies BB_API_TOKEN:

printf '%s' "$BB_API_TOKEN" | bb auth login -u [email protected] --with-token

Or provide the email through the existing environment variable:

export BB_USERNAME=[email protected]
bb auth login  # BB_API_TOKEN must already be supplied by your secret store

Interactive login can also ask for the email and token, with the token hidden as you type. Outside a terminal, missing credentials are an error.

--with-token reads and trims all of stdin. Empty input fails with 5001; combining it with -p/--password fails with 5002. See Auth commands for the full option reference.

Tip

Use stdin or your CI secret store. Passing a token with -p exposes it in process arguments and potentially shell history. Avoid saving literal tokens in shell startup files.

Check auth status

bb auth status

✓ Logged in to Bitbucket
  Authentication: OAuth
  Username: jdoe
  Display name: Jane Doe
  Account ID: 5f1a2b3c4d5e6f7a8b9c0d1e
  Token expires: in 1h 42m
  Default workspace: acme

The API returns the displayed account username; it is distinct from the email used for API-token login. Expiry appears only for OAuth, and the default workspace appears only when configured. Add --json for structured output. When you are not logged in, bb auth status exits 1. Run bb doctor to check network access, token scopes, and the rest of your setup as well.

Logout

bb auth logout

Logout removes credentials for the active authentication method. OAuth logout also attempts to revoke the OAuth token. It preserves other settings. If revocation fails, local credentials are still removed and the command reports revokeFailed: true under --json.

Multiple accounts

bb keeps any number of named accounts, for example a work and a personal Atlassian login. Your first login is the default account, and an existing single-account config is read as default too, so nothing changes until you add a second one:

bb auth login --account personal      # add (or re-authenticate) an account
bb auth switch work                   # change the active account
bb --account personal pr list         # one command as another account
BB_ACCOUNT=personal bb pr list        # same, from the environment

bb auth login without --account re-authenticates the current account, and the account you log in to becomes the active one. bb auth status shows which account is in use and lists the others. Logging out of the active account switches to another saved account if there is one.

Account names use letters, digits, ., _, -, @ and +, so an email address works as a name.

Configuration storage

By default, credentials are plaintext in ~/.config/bb/config.json on Linux/macOS, or %APPDATA%\bb\config.json on Windows.

To keep tokens in the OS keychain instead (macOS Keychain, Windows Credential Manager, or libsecret on Linux):

bb config set credentialStorage keychain

This moves the tokens of every saved account right away, and later logins and OAuth refreshes write there too. The config file keeps only non-secret fields such as the account email and token expiry. bb config set credentialStorage file moves them back. The keychain needs Bun 1.2.21 or newer (the standalone binaries include it) and, on Linux, a running secret service such as GNOME Keyring. If the keychain is unavailable, bb fails with error 4001/4002 instead of silently writing plaintext. Keep file storage on headless CI hosts.

On Linux/macOS, the CLI writes directory mode 700 and file mode 600 and rejects group/other access with error 4001. Windows uses profile permissions and skips that mode check. These permissions do not hide the file from tools running as your user. See Configuration file.

Next steps

• Quick start
• Repository context
• Troubleshooting