What are the primary authentication methods for the Bitbucket API?

The primary methods are OAuth 2.0, suitable for third-party applications, and App Passwords, ideal for scripts and direct programmatic access.

When should I use OAuth 2.0 versus an App Password?

Use OAuth 2.0 for applications needing to access Bitbucket on behalf of users, often with a user consent flow. Use App Passwords for personal scripts, CI/CD tools, or server-side integrations that don't involve user interaction.

How do I generate an App Password for Bitbucket?

Log into Bitbucket Cloud, go to Personal settings, select 'App passwords' under 'Access management', and click 'Create new app password', specifying the necessary permissions.

What permissions (scopes) should I grant to my API credentials?

Always grant the minimum necessary permissions (scopes) required for your application or script to function. This follows the principle of least privilege to minimize potential security risks.

Are App Passwords as secure as my main Bitbucket password?

App Passwords should be treated with the same high level of security as your main password. They are distinct and revocable, offering a better security posture than exposing your primary password, but still grant access to your account.

How often should I rotate my API credentials?

It is a best practice to regularly rotate your API credentials, such as app passwords and OAuth tokens, to mitigate the risk of compromise. The exact frequency can depend on your organization's security policies.

Can I use Basic Authentication with my Bitbucket username and password?

While technically possible for some legacy endpoints, it is strongly discouraged. App Passwords provide a more secure alternative for Basic Authentication, as they are revocable and scoped, unlike your main password.

Bitbucket API Authentication: Methods, Credentials & Security

Authentication overview

The Bitbucket API requires authentication for nearly all operations to ensure secure access to user data and resources such as repositories, pull requests, and project settings. The primary methods for authentication are OAuth 2.0 and App Passwords. Choosing the correct method depends on the nature of the integration: OAuth 2.0 is generally preferred for third-party applications and services, while App Passwords are suitable for scripts, command-line tools, or direct integrations where a user's full password should not be exposed. All API requests must be made over HTTPS to prevent eavesdropping and data tampering, adhering to modern security standards for web communication HTTPS security best practices.

The Bitbucket Cloud REST API provides endpoints for managing source code, CI/CD pipelines, and integrating with other Atlassian products. Proper authentication ensures that requests are authorized with the appropriate permissions, preventing unauthorized access and maintaining data integrity. Users should always refer to the official Bitbucket Cloud REST API documentation for the most current and detailed authentication instructions.

Supported authentication methods

Bitbucket API supports two main authentication methods, each designed for different use cases and security requirements:

OAuth 2.0: This open standard is the recommended method for third-party applications and services that need to access Bitbucket resources on behalf of a user without handling their credentials directly. OAuth 2.0 tokens provide granular control over permissions and can be revoked independently.
App Passwords: These are securely generated, unique passwords that grant specific access to a Bitbucket account via the API. They are distinct from a user's main password and can be used for scripts, continuous integration environments, or other programmatic access where a full user login flow is not practical.

The table below summarizes these methods:

Method	When to Use	Security Level	Typical Use Case
OAuth 2.0	Third-party apps, multi-user access, granular permissions	High (token-based, revocable, scoped)	Integrating a CI/CD service, project management tool, or IDE plugin
App Passwords	Scripts, command-line tools, single-user automation	Medium-High (separate from main password, revocable, scoped)	Automated deployment scripts, personal API integrations

OAuth 2.0

Bitbucket API implements the OAuth 2.0 authorization framework, specifically supporting the Authorization Code grant type for web applications and the Client Credentials grant type for server-to-server integrations. This allows applications to obtain access tokens that grant specific permissions to a user's Bitbucket resources without ever exposing the user's password to the application. The OAuth 2.0 flow typically involves:

Registering your application with Bitbucket to obtain a Client ID and Client Secret.
Redirecting the user to Bitbucket's authorization page, where they grant your application specific permissions (scopes).
Bitbucket redirects the user back to your application with an authorization code.
Your application exchanges the authorization code for an access token and optionally a refresh token using its Client ID and Client Secret.
The access token is then used to make authenticated requests to the Bitbucket API.

For more details on OAuth 2.0 flows, refer to the OAuth 2.0 specification and the Bitbucket Cloud OAuth 2.0 guide.

App Passwords

App passwords provide a more straightforward authentication method for scenarios where a full OAuth flow is unnecessary or impractical. An app password is a unique, randomly generated password that can be configured with specific permissions (scopes) for a Bitbucket user account. It acts as a substitute for your regular password when interacting with the API or Git clients. To generate an app password:

Log in to Bitbucket Cloud.
Navigate to your personal settings (avatar > 'Personal settings').
Select 'App passwords' under 'Access management'.
Click 'Create new app password', provide a label, and select the necessary permissions (scopes).
Copy the generated app password immediately, as it will not be displayed again.

App passwords should be treated with the same level of security as a regular password and stored securely. Refer to the Bitbucket documentation on app passwords for detailed instructions.

Getting your credentials

For OAuth 2.0 (Client ID and Secret)

To obtain OAuth 2.0 credentials, you must register your application with Bitbucket. This process typically involves:

Log in to Bitbucket: Access your Bitbucket Cloud account.
Navigate to Workspace Settings: Go to the workspace your application will interact with.
Access OAuth Consumers: Under 'Apps and features', select 'OAuth consumers'.
Register New Consumer: Click 'Add consumer'.
Configure Consumer Details: Provide details such as the application name, description, callback URL (for Authorization Code flow), and specify the required permissions (scopes). The callback URL is crucial for Bitbucket to redirect the user back to your application after authorization Bitbucket OAuth consumer registration.
Retrieve Credentials: After saving, Bitbucket will display your Client ID and Client Secret. Store these securely.

For App Passwords

As described in the previous section:

Log in to Bitbucket Cloud.
Go to Personal settings.
Select 'App passwords'.
Click 'Create new app password'.
Provide a label and select permissions.
Copy the generated password.

Remember that app passwords are tied to a specific user's account and inherit that user's permissions, constrained by the scopes you define when creating the password.

Authenticated request example

The following example demonstrates how to make an authenticated request to the Bitbucket API using an App Password via curl to list repositories for a workspace. Replace <YOUR_USERNAME> and <YOUR_APP_PASSWORD> with your actual Bitbucket username and the app password you generated, and <YOUR_WORKSPACE_ID> with the ID of your Bitbucket workspace.

curl -u "<YOUR_USERNAME>:<YOUR_APP_PASSWORD>" \
  https://api.bitbucket.org/2.0/repositories/<YOUR_WORKSPACE_ID>

For OAuth 2.0, the process involves obtaining an access token first, then including it in the Authorization header:

export ACCESS_TOKEN="<YOUR_OAUTH_ACCESS_TOKEN>"

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.bitbucket.org/2.0/repositories/<YOUR_WORKSPACE_ID>

This example retrieves a list of repositories within a specified workspace. The -u flag in the App Password example provides HTTP Basic Authentication, where the username and app password form the credentials. For OAuth 2.0, the Bearer token is the standard way to transmit the access token in the Authorization header, as defined by the RFC 6750 for Bearer Token Usage.

Security best practices

Securing your Bitbucket API integrations is critical to protecting your code and data. Adhere to these best practices:

Use OAuth 2.0 for Third-Party Applications: Whenever possible, use OAuth 2.0 instead of app passwords for applications that interact with multiple user accounts or that you don't fully control. OAuth tokens are designed for limited scope and duration, reducing the risk of a full account compromise Bitbucket OAuth 2.0 guide.
Scope Permissions Minimally: When creating OAuth consumers or app passwords, grant only the minimum necessary permissions (scopes) required for the application's function. Avoid granting broad 'write' or 'admin' access unless absolutely essential.
Protect Client Secrets and App Passwords: Store your OAuth Client Secrets and App Passwords securely. Do not hardcode them directly into your application code. Utilize environment variables, secret management services (e.g., AWS Secrets Manager, Azure Key Vault, Google Secret Manager), or secure configuration files.
Rotate Credentials Regularly: Periodically revoke and regenerate your app passwords and OAuth refresh tokens. This mitigates the risk if credentials are leaked without your knowledge.
Monitor API Usage: Keep an eye on your Bitbucket audit logs and API usage. Unusual activity can indicate a compromised credential or unauthorized access.
Use HTTPS Everywhere: Ensure all communication with the Bitbucket API uses HTTPS. This encrypts data in transit, protecting against man-in-the-middle attacks. This is enforced by Bitbucket, but developers should verify their clients are not bypassing this.
Implement Token Refresh and Revocation: For OAuth 2.0, implement mechanisms to refresh access tokens before they expire and to revoke tokens if a security incident occurs or an integration is no longer needed.
Avoid Storing Sensitive Data Unnecessarily: Do not store Bitbucket API responses that contain sensitive information unless absolutely necessary, and if stored, ensure they are encrypted at rest.