Auth Commands

Manage authentication with Bitbucket.

Global options available on all auth commands: --json, --no-color.

`bb auth login`

Authenticate with Bitbucket using OAuth (default) or an API token.

bb auth login [options]

Options

Option	Description
`-u, --username <username>`	Bitbucket username (implies API token auth)
`-p, --password <password>`	Bitbucket API token (implies API token auth)
`--app-password`	Use API token authentication instead of OAuth (legacy flag name — uses API tokens, not app passwords)
`--client-id <clientId>`	Custom OAuth consumer client ID
`--client-secret <clientSecret>`	Custom OAuth consumer client secret
`--json`	Output as JSON

Examples

# Login with OAuth (opens browser)
bb auth login

# Login with a custom OAuth consumer
bb auth login --client-id YOUR_KEY --client-secret YOUR_SECRET

# Login with API token
bb auth login -u myuser -p your-api-token

# Login using environment variables (API token)
export BB_USERNAME=myuser
export BB_API_TOKEN=your-api-token
bb auth login

How It Works

OAuth flow (default):

The CLI starts a local callback server and opens your browser
You authorize the CLI on Bitbucket’s consent screen
Bitbucket redirects back to the CLI with an authorization code
The CLI exchanges the code for access and refresh tokens
Tokens are stored in your config file
Access tokens expire after 2 hours and are refreshed automatically

API token flow (with -u/-p or --app-password):

You provide your Bitbucket username and API token
The CLI stores the credentials in your config file
The CLI verifies the credentials by fetching your user information
If verification fails, credentials are not saved

Auth Method Detection

The CLI determines which flow to use based on flags:

Condition	Auth Method
No flags	OAuth
`-u` or `-p` provided	API Token
`--app-password` flag	API Token
`BB_API_TOKEN` env var set	API Token

Required Scopes (API Token)

When using API tokens, your token needs these 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

OAuth scopes are requested automatically during authorization.

See the Authentication guide for detailed setup instructions.

`bb auth logout`

Log out of Bitbucket and remove stored credentials.

bb auth logout [options]

Options

Option	Description
`--json`	Output as JSON

Examples

bb auth logout

What Gets Removed

OAuth: Revokes the token on Bitbucket’s side, then removes oauthAccessToken, oauthRefreshToken, oauthExpiresAt, authMethod, and custom OAuth consumer credentials from the config file.
API Token: Removes username and apiToken from the config file.

Other settings like defaultWorkspace, skipVersionCheck, and versionCheckInterval are preserved.

`bb auth status`

Show current authentication status and account information.

bb auth status [options]

Options

Option	Description
`--json`	Output as JSON

Examples

# Check authentication status
bb auth status

# Get status as JSON
bb auth status --json

Output

When authenticated with OAuth:

✓ Logged in to Bitbucket
  Authentication: OAuth
  Username: myuser
  Display name: My Name
  Account ID: 123456789
  Token expires: in 1h 42m

When authenticated with API token:

✓ Logged in to Bitbucket
  Authentication: API Token
  Username: myuser
  Display name: My Name
  Account ID: 123456789

When not authenticated:

ℹ Not logged in
Run bb auth login to authenticate.

`bb auth token`

Print the current access token.

bb auth token [options]

Options

Option	Description
`--json`	Output as JSON

Examples

# Print the token
bb auth token

# Get token as JSON
bb auth token --json

Output

OAuth: Prints the bearer access token (automatically refreshes if expired).
API Token: Prints a base64-encoded username:apiToken string suitable for HTTP Basic auth headers.

Use Cases

This is useful for:

Debugging authentication issues
Using the token with other tools or scripts
Verifying token format