What is the most secure way to authenticate with Bitbucket for API access?

For API access, OAuth 2.0 is generally the most secure method, especially for third-party applications. It uses token-based authentication with scoped permissions and avoids direct credential handling. For scripts and CI/CD, app passwords offer a good balance of security and control when configured with minimal necessary permissions.

Can I use my Bitbucket username and password for Git operations?

While Bitbucket used to support basic authentication with username and password for Git over HTTPS, it is generally discouraged for security reasons. SSH keys are the recommended and more secure method for Git operations, providing cryptographic authentication without transmitting your password.

How do I revoke an app password in Bitbucket?

To revoke an app password, log in to Bitbucket, go to your personal 'Bitbucket settings', then 'App passwords'. You will see a list of your generated app passwords, each with an option to revoke it. Revoking a password immediately invalidates it.

What are OAuth scopes and why are they important?

OAuth scopes define the specific permissions an application requests from a user (e.g., 'repository:read', 'issue:write'). They are important because they enforce the principle of least privilege, ensuring that an application only has access to the resources it needs, thereby limiting potential damage if the access token is compromised.

Is it safe to store app passwords in environment variables?

Storing app passwords in environment variables is generally safer than hardcoding them directly into code, especially in CI/CD environments. However, for highly sensitive scenarios, dedicated secret management services provide even greater security by encrypting and controlling access to credentials.

How often should I rotate my Bitbucket credentials?

Regular credential rotation is a good security practice. While there's no universal rule, rotating app passwords and OAuth tokens every 90-180 days is a common recommendation. Promptly rotate credentials immediately if you suspect they might have been compromised.

Can I use a single app password for multiple projects or repositories?

Yes, an app password can be configured with permissions that apply across multiple projects or repositories within your workspace. However, for granular control and adherence to the principle of least privilege, it's often better to create separate app passwords with specific scopes for different tools or tasks if their access needs vary significantly.

Bitbucket Authentication: Methods & Security Best Practices (2026)

Authentication overview

Bitbucket provides several mechanisms to authenticate users and applications interacting with its repositories and API. The choice of authentication method depends on the specific use case, whether it's a human user performing Git operations, an automated script accessing the Bitbucket Cloud REST API, or a third-party application integrating with Bitbucket features. Proper authentication ensures that only authorized entities can access code, manage repositories, and trigger CI/CD pipelines.

For direct user interaction via the web interface, Bitbucket uses Atlassian account credentials, often secured with two-factor authentication (2FA). For programmatic access, Bitbucket supports industry-standard protocols and proprietary mechanisms tailored for different scenarios. Understanding these methods is crucial for maintaining secure development workflows and integrating external tools effectively.

Supported authentication methods

Bitbucket supports several authentication methods, each designed for specific interaction patterns:

OAuth 2.0: This is the recommended method for third-party applications and services to access Bitbucket on behalf of users without directly handling user credentials. OAuth 2.0 provides a secure, delegated authorization framework. Bitbucket implements the Authorization Code Grant flow, allowing applications to request specific scopes of access (e.g., read repository, write issues) from users. For more information on the protocol, refer to the OAuth 2.0 specification.
App Passwords: These are an alternative to using your main Atlassian account password for command-line tools, scripts, and other applications that don't support OAuth 2.0. App passwords are generated within Bitbucket user settings and can be revoked independently without affecting your primary account password. They offer granular control by allowing you to specify permissions (scopes) for each password, such as 'Read' or 'Write' access to repositories or 'Admin' access to projects. This method is particularly useful for CI/CD systems like Bitbucket Pipelines or external build servers needing programmatic access.
SSH Keys: For Git operations (cloning, pushing, pulling), SSH (Secure Shell) keys provide a highly secure and convenient authentication method. Instead of entering a password repeatedly, users configure a public SSH key in their Bitbucket account. When connecting to Bitbucket via SSH, the client uses the corresponding private key to authenticate. This method is generally preferred for developers working from their local machines due to its security benefits and ease of use after initial setup. Bitbucket supports RSA and ED25519 key types.
Basic Authentication (Legacy API Access): While technically supported for older API versions or specific endpoints, Bitbucket generally discourms the use of Basic Authentication (username and password directly in the request header) due to its inherent security risks. For new integrations and modern API access, OAuth 2.0 or app passwords are the secure and recommended alternatives.

Comparison of Authentication Methods

Method	When to Use	Security Level
OAuth 2.0	Third-party applications, delegated access, API integrations	High (token-based, scoped permissions, no direct credential sharing)
App Passwords	Scripts, CLI tools, CI/CD systems, programmatic access where OAuth 2.0 is not feasible	Medium-High (scoped permissions, revocable, distinct from main password)
SSH Keys	Git command-line operations (clone, push, pull)	High (cryptographically secure, no password transmission)
Basic Auth	Legacy API integrations (generally discouraged for new development)	Low (transmits credentials directly, vulnerable to interception)

Getting your credentials

The process for obtaining credentials varies by authentication method:

For OAuth 2.0

Register an OAuth Consumer: Navigate to your Bitbucket workspace settings and select OAuth consumers. Create a new consumer, providing a name, description, callback URL, and selecting the necessary permissions (scopes). This generates a client ID and client secret.
Implement the OAuth Flow: Your application will redirect users to Bitbucket for authorization. After the user grants permission, Bitbucket redirects back to your specified callback URL with an authorization code.
Exchange Code for Access Token: Your application then exchanges this authorization code for an access token and a refresh token by making a POST request to Bitbucket's token endpoint. The access token is used to make API requests on behalf of the user. For detailed steps, consult the Bitbucket OAuth 2.0 documentation.

For App Passwords

Access Personal Settings: Log in to Bitbucket and go to your personal Bitbucket settings.
Generate App Password: Under 'Access management', select App passwords. Click 'Create new app password'.
Define Permissions: Provide a label for the password and carefully select the specific permissions (scopes) required for the task. For example, if a script only needs to read repository contents, grant 'Read' access to repositories, not 'Write' or 'Admin'.
Save the Password: Bitbucket will display the generated app password once. Copy it immediately, as it will not be shown again. Store it securely.

For SSH Keys

Generate an SSH Key Pair: If you don't already have one, generate an SSH key pair on your local machine using a tool like ssh-keygen. Standard practice involves creating RSA or ED25519 keys without a passphrase for automation or with a strong passphrase for interactive use. For example: ssh-keygen -t ed25519 -C "[email protected]".
Copy Public Key: Copy the contents of your public key file (e.g., ~/.ssh/id_ed25519.pub).
Add Key to Bitbucket: Log in to Bitbucket, go to your personal Bitbucket settings, and select SSH keys. Click 'Add key', paste your public key, and provide a label.
Test Connection: Verify your SSH setup by running ssh -T [email protected] from your terminal.

Authenticated request example

This example demonstrates making an authenticated request to the Bitbucket Cloud REST API using an app password with cURL to list repositories for a workspace. Replace <your_username>, <your_app_password>, and <your_workspace_id> with your actual credentials and workspace identifier.

curl -u "<your_username>:<your_app_password>" \
     https://api.bitbucket.org/2.0/repositories/<your_workspace_id>

For Python, using the requests library for an app password authentication:

import requests

username = "<your_username>"
app_password = "<your_app_password>"
workspace_id = "<your_workspace_id>"

url = f"https://api.bitbucket.org/2.0/repositories/{workspace_id}"

response = requests.get(url, auth=(username, app_password))

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

When using OAuth 2.0, requests would include an Authorization: Bearer <access_token> header instead of Basic Auth. For instance:

curl -H "Authorization: Bearer <your_oauth_access_token>" \
     https://api.bitbucket.org/2.0/user/permissions/workspaces

Security best practices

Adhering to security best practices is essential when managing authentication credentials for Bitbucket:

Use Two-Factor Authentication (2FA): Enable 2FA on your Atlassian account to add an extra layer of security against unauthorized access, even if your password is compromised. This is a critical step for all users.
Principle of Least Privilege: When creating app passwords or configuring OAuth consumers, grant only the minimum necessary permissions (scopes). For example, a CI/CD pipeline that only needs to clone a repository should not have 'Admin' access. This limits the potential damage if a credential is leaked.
Rotate Credentials Regularly: Periodically revoke and regenerate app passwords and OAuth tokens. This practice reduces the window of opportunity for attackers if a credential is compromised without detection.
Store Credentials Securely: Never hardcode credentials directly into your source code. Use environment variables, secure configuration files, or dedicated secret management services (e.g., AWS Secrets Manager, HashiCorp Vault) for storing sensitive information like app passwords and client secrets.
Protect SSH Private Keys: Ensure your SSH private keys are stored with strong file permissions (e.g., chmod 400 ~/.ssh/id_rsa) and, for interactive use, consider using a strong passphrase to encrypt the private key. Avoid sharing private keys.
Monitor Access Logs: Regularly review Bitbucket's audit logs for unusual activity or unauthorized access attempts. Unusual login locations or frequent failed login attempts can indicate a security breach.
Revoke Unused Credentials: Promptly revoke any app passwords or OAuth tokens that are no longer in use or associated with departed team members. This reduces the attack surface.
Be Cautious with Public Repositories: Avoid committing any sensitive information, including API keys, passwords, or tokens, to even private repositories. Implement pre-commit hooks or automated secret scanning tools to prevent accidental exposure.
Understand OAuth Scopes: When developing OAuth applications, clearly communicate the requested permissions to users. Ensure your application only requests scopes absolutely necessary for its functionality, building user trust and minimizing security risks. The IETF RFC 6749 provides comprehensive details on OAuth 2.0 security.