Skip to content
Bitbucket CLI Bitbucket CLI

Authentication

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

Section titled “OAuth (Recommended)”

The simplest way to authenticate. Just run:

Terminal window
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.

Using a Custom OAuth Consumer

Section titled “Using a Custom OAuth Consumer”

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

Terminal window
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.

API Token (for CI/CD and headless environments)

Section titled “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
      • write:repository:bitbucket — create repositories
      • admin:repository:bitbucket — delete repositories (optional)
      • read:pullrequest:bitbucket — list and view pull requests
      • write:pullrequest:bitbucket — create, edit, merge, approve, decline pull requests
    7. Click Create
    8. Copy the generated token - you won’t be able to see it again!

  2. Authenticate

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

    Or using environment variables:

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

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

Check Auth Status

Section titled “Check Auth Status”
Terminal window
bb auth status

This shows your current authentication method, account information, and token expiry (for OAuth).

Logout

Section titled “Logout”
Terminal window
bb auth logout

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

Configuration Storage

Section titled “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.

Next Steps

Section titled “Next Steps”