Auth Commands

Manage authentication with Bitbucket.

Global options available on all auth commands: --json [fields], --jq <expression>, --no-color, --no-unicode, --locale <locale>. See Global flags for the full list.

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)
--with-token	Read the API token from stdin so it never appears in shell history or process args (implies API token auth)
--app-password	Use API token authentication instead of OAuth (see the note below)
--client-id <clientId>	Custom OAuth consumer client ID
--client-secret <clientSecret>	Custom OAuth consumer client secret

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 by piping the token via stdin (keeps it out of shell history and `ps`)
echo "$BB_API_TOKEN" | bb auth login -u myuser --with-token

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

Tip

--with-token is the safest way to pass a token. Unlike -p, the token is read from stdin, so it never lands in your shell history or in process-listing tools like ps. It pairs well with secret managers, e.g. my-secret-tool get bb-token | bb auth login -u myuser --with-token.

Two rules: --with-token cannot be combined with -p/--password (hard error, VALIDATION_INVALID), and it reads all of stdin and trims it, so an empty stdin fails instead of prompting — bb auth login -u me --with-token < /dev/null errors with No API token found on stdin.

How it works

OAuth is used unless any of --app-password, --with-token, -u, -p, or the BB_API_TOKEN environment variable is present.

OAuth flow (default):

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

Note

The OAuth flow needs a browser that can reach a loopback callback server on http://localhost:19872/callback. There is no device-code flow, so on headless hosts (SSH sessions, containers, CI) use API token auth — ideally --with-token — instead.

API token flow:

1. You provide your Bitbucket username and API token (token via -p, piped to stdin with --with-token, or the BB_API_TOKEN environment variable)
2. The CLI stores the credentials in your config file
3. The CLI verifies the credentials by fetching your user information
4. If verification fails, credentials are not saved

Note

The --app-password flag is a legacy name. It triggers API token authentication, not Bitbucket app passwords (which are deprecated). Prefer -u/-p, --with-token, or the environment variables.

Required scopes (API token)

bb auth login and bb auth status need read:user:bitbucket to verify your identity, and so does bb pr list --mine (it resolves your account UUID).

Repository and pull request commands need read:repository:bitbucket and read:pullrequest:bitbucket, plus the matching write: scopes to create, edit, merge, approve, or decline. Creating a repository needs the admin scope (legacy repository:admin) and deleting one needs the delete scope (legacy repository:delete); Atlassian publishes these as admin:repository:bitbucket and delete:repository:bitbucket.

Everything else — pipelines, snippets, projects — needs its own scope. See Token scopes for the per-command table.

OAuth logins request a fixed scope set: account repository repository:admin pullrequest pullrequest:write. Commands outside repositories and pull requests (bb pipeline, bb snippet, bb project) are not covered, and neither is bb repo delete. Use an API token with the matching scopes for those.

See the Authentication guide for setup instructions.

---

bb auth logout

Log out of Bitbucket and remove stored credentials.

bb auth logout [options]

Examples

bb auth logout

# Machine-readable result
bb auth logout --json

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.

If revocation fails, the CLI still clears local credentials and warns you to revoke the token manually (revokeFailed: true in --json).

---

bb auth status

Show current authentication status and account information.

bb auth status [options]

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: 712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f
  Token expires: in 1h 42m
  Default workspace: myworkspace

When authenticated with API token:

✓ Logged in to Bitbucket
  Authentication: API Token
  Username: myuser
  Display name: My Name
  Account ID: 712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f
  Default workspace: myworkspace

The Default workspace: line appears only when defaultWorkspace is set. On an OAuth login with a stale token, Token expires: reads expired (will refresh automatically).

When not authenticated:

ℹ Not logged in
Run bb auth login to authenticate.

Caution

bb auth status --json reports method: "basic" for API-token logins, while bb auth login --json reports method: "api_token" for the same credentials. In scripts, match on !== "oauth" rather than on either literal. See JSON output for the full payloads.

---

bb auth token

Print the current access token.

bb auth token [options]

Examples

# Print the token
bb auth token

# Copy it to the clipboard
bb auth token | pbcopy

# Use it against the raw API (OAuth login — bearer token)
curl -H "Authorization: Bearer $(bb auth token)" https://api.bitbucket.org/2.0/user

# Use it against the raw API (API token login — base64 basic credentials)
curl -H "Authorization: Basic $(bb auth token)" https://api.bitbucket.org/2.0/user

# Get token as JSON
bb auth token --json

Output

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

Caution

Anyone holding this token has your Bitbucket access, within the scopes you granted. Don’t paste it into logs, CI output, or issue reports.