Authentication

The Bitbucket CLI supports two authentication methods: OAuth (recommended) and API tokens.

OAuth (recommended)

bb auth login

This opens your browser where you authorize the CLI with your Bitbucket account. No tokens to copy, no scopes to select manually. Tokens expire after 2 hours and are refreshed automatically.

If BB_API_TOKEN is exported in your shell, bb auth login uses API-token auth instead of opening a browser. It is the variable being set that switches the flow, not its value — even export BB_API_TOKEN= does it. Run unset BB_API_TOKEN first if you want OAuth.

Caution

OAuth needs a browser that can reach a loopback callback server on http://localhost:19872/callback. There is no device-code flow, so if you’re on a headless host (SSH session, container, CI runner) where no browser is available, use an API token instead.

Using a custom OAuth consumer

Organizations can use their own OAuth consumer instead of the built-in default:

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

To set up a custom OAuth consumer:

1. Go to Workspace settings > Apps and features > OAuth consumers
2. Click Add consumer
3. Set Callback URL to http://localhost:19872/callback
4. Grant permissions: Account (Read), Repositories (Read, Write, Admin), Pull requests (Read, Write)
5. Save and use the generated Key as --client-id and Secret as --client-secret

Custom credentials are stored in your config file for subsequent logins.

OAuth cannot reach every command

The CLI requests a hardcoded OAuth scope set: account repository repository:admin pullrequest pullrequest:write. A custom consumer cannot widen it. bb pipeline, bb snippet, bb project and bb repo delete are not covered — use an API token for those. See Token Scopes.

---

API token (for CI/CD and headless environments)

Use API tokens when a browser is not available (SSH sessions, Docker containers, CI/CD pipelines).

1. Create an API token

   1. Log in to Bitbucket

   2. Go to Personal settings (click your avatar in the bottom left)

   3. Navigate to API tokens under “Access management”

   4. Click Create API token

   5. Give it a descriptive name (e.g., “Bitbucket CLI”)

   6. Select the required scopes:

      • read:user:bitbucket — verify your identity
      • read:repository:bitbucket — list and view repositories, commits, build statuses
      • write:repository:bitbucket — set commit build statuses
      • admin:repository:bitbucket — create repositories, manage default reviewers
      • delete:repository:bitbucket — delete repositories (optional)
      • read:pullrequest:bitbucket — list and view pull requests
      • write:pullrequest:bitbucket — create, edit, merge, approve, decline pull requests

      See Token Scopes for a per-command breakdown if you want to mint a token with the minimum scope set for your workflow.

   7. Click Create

   8. Copy the generated token — Bitbucket will not show it again.

2. Authenticate

   bb auth login -u your-username -p your-api-token

   Or pipe the token via stdin so it never lands in your shell history or ps output (recommended):

   echo "$BB_API_TOKEN" | bb auth login -u your-username --with-token

   --with-token reads all of stdin and trims it, so a trailing newline is fine. It cannot be combined with -p — that fails with error 5002 (“Cannot combine –password with –with-token”). If nothing is piped in, the login fails with 5001 (“No API token found on stdin”).

   Or using environment variables:

   export BB_USERNAME=your-username
   export BB_API_TOKEN=your-api-token
   bb auth login

Tip

Prefer --with-token or BB_API_TOKEN over -p in scripts and CI. Passing a secret as a command-line argument leaves it visible in shell history and to anyone who can list processes (ps).

See Environment Variables Reference for more details on using environment variables in scripts and CI/CD.

---

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

Token expires only appears for OAuth logins. Default workspace only appears once one is configured. Add --json for a machine-readable version.

Logout

bb auth logout

This removes stored credentials and revokes your OAuth token (if using OAuth). Non-auth settings are preserved.

Configuration storage

Credentials are stored in:

• Linux/macOS: ~/.config/bb/config.json
• Windows: %APPDATA%\bb\config.json

See Configuration File Reference for details on the config file format.

Caution

Tokens are stored in plaintext JSON. On Linux and macOS the CLI writes the file with mode 600 and the directory with mode 700, and refuses to read either if any group or other permission bit is set — you get error 4001 with the exact chmod to run. Windows skips the check.

Next steps

• Quick Start Guide - Get up and running in 60 seconds
• Repository Context - How the CLI detects your workspace/repo
• Troubleshooting - Common authentication issues and solutions