How do I authenticate with Bitbucket?

Bitbucket supports four authentication methods: (1) App Passwords — the recommended method for scripts and CLI tools. Generate in Account Settings > App Passwords. Use as password when prompted by Git or in HTTP Basic auth headers. (2) OAuth 2.0 — for web applications that need to act on behalf of users. (3) SSH Keys — for Git operations over SSH without entering passwords. (4) Repository Access Tokens — scoped tokens for specific repositories, ideal for CI/CD. Password authentication was deprecated in 2022.

What is a Bitbucket App Password?

A Bitbucket App Password is a token that you use instead of your account password for authenticating Git and API operations. Unlike your account password, App Passwords can be scoped to specific permissions (repositories, pipelines, pull requests, etc.) and can be revoked individually. Create one at: bitbucket.org > Account Settings > App Passwords. Use the App Password as the password in HTTP Basic authentication or when Git prompts for credentials.

// Bitbucket Authentication

Bitbucket Auth Guide —
App Passwords, OAuth, SSH & Tokens

All Bitbucket authentication methods explained. App Passwords, OAuth 2.0, SSH keys, and Access Tokens — with curl command builder for the REST API.

App Passwords OAuth 2.0 SSH Keys Access Tokens REST API

Workspace

Auth method

Username / Token

API endpoint

Repository slug (if needed)

Fill in workspace and credentials to generate a curl command

Bitbucket authentication methods

Recommended

App Passwords

Token scoped to specific permissions. Use as password in HTTP Basic auth or Git prompts. Supports 2FA accounts. Create at Account Settings → App Passwords.

OAuth 2.0

For web apps acting on behalf of users. Authorization Code flow for user-facing apps. Client Credentials for server-to-server. Tokens expire and must be refreshed.

SSH Key

SSH Keys

Add public key to Bitbucket account. Clone/push with git@bitbucket.org:workspace/repo.git — no password prompts. Best for interactive development.

CI/CD

Repository Access Tokens

Scoped to a single repository. Ideal for CI/CD pipelines and automation. Not tied to a user account — survives team member changes.

Deprecated

Password Authentication

Account password auth was deprecated in March 2022. No longer supported for Git or API. Use App Passwords instead — they provide the same access with better security.

Authentication examples

# ─── APP PASSWORD — HTTP Basic Auth (REST API) ───


curl -u username:app-password   
https://api.bitbucket.org/2.0/repositories/workspace

# ─── APP PASSWORD — Git clone over HTTPS ───
git clone https://username:app-password@bitbucket.org/workspace/repo.git

# Store credentials to avoid re-entering (Git credential helper)
git config –global credential.helper store

# ─── REPOSITORY ACCESS TOKEN — Bearer ───
curl -H “Authorization: Bearer REPO_ACCESS_TOKEN”   
https://api.bitbucket.org/2.0/repositories/workspace/repo

# ─── OAUTH 2.0 — Get access token ───
curl -X POST https://bitbucket.org/site/oauth2/access_token   
-u CLIENT_ID:CLIENT_SECRET   
-d “grant_type=client_credentials”

# ─── OAUTH 2.0 — Use access token ───
curl -H “Authorization: Bearer ACCESS_TOKEN”   
https://api.bitbucket.org/2.0/user

# ─── SSH — Add key and clone ───
ssh-keygen -t ed25519 -C “your@email.com”
# Add ~/.ssh/id_ed25519.pub to Bitbucket Account Settings > SSH Keys
git clone git@bitbucket.org:workspace/repo.git

Bitbucket auth guide

Creating a Bitbucket App Password (step by step)
Go to bitbucket.org → click your avatar → Account Settings → App Passwords → Create app password. Give it a label (e.g., "CI Pipeline" or "Local Dev"). Select the permissions you need: Repositories (Read/Write), Pull Requests (Read/Write), Pipelines (Read/Write/Edit). Click Create. Copy the generated token immediately — it is only shown once. Use it as the password in HTTP Basic auth or Git prompts with your Bitbucket username.

Repository Access Tokens for CI/CD
Go to your repository → Repository Settings → Access Tokens → Create repository access token. Choose scopes: read (clone/fetch), write (push). The token is a Bearer token — include it in the Authorization header: Authorization: Bearer TOKEN. For Git clone over HTTPS: git clone https://x-token-auth:TOKEN@bitbucket.org/workspace/repo.git. Repository Access Tokens are not tied to a user account — they won't break if a team member leaves.

Authenticating in Bitbucket Pipelines
Within Bitbucket Pipelines, the BITBUCKET_CLONE_DIR, BITBUCKET_WORKSPACE, and BITBUCKET_REPO_SLUG variables are available automatically. For API access from pipelines, create a Repository Access Token and store it as a secured pipeline variable. Access it in your pipeline YAML as $REPO_TOKEN. Never hardcode tokens in bitbucket-pipelines.yml.

FAQ — Bitbucket auth

For API and Git over HTTPS: use an App Password (Account Settings → App Passwords). Your Bitbucket account password no longer works for authentication — it was deprecated in 2022. For CI/CD: use a Repository Access Token (scoped to one repo, not tied to a user). For Git over SSH: add your public key to Account Settings → SSH Keys. For web apps: use OAuth 2.0 with the Authorization Code or Client Credentials flow.

An App Password is a scoped token that replaces your account password for authentication. To create: bitbucket.org → Account Settings → App Passwords → Create app password. Choose a label and select the needed permissions. Use it as the password value in HTTP Basic auth or when Git prompts for credentials. It shows only once after creation — copy it immediately. App Passwords support 2FA accounts.

Use a Repository Access Token (Repository Settings → Access Tokens) for CI/CD — it's scoped to one repo and not tied to a user account. Store the token as a secured Bitbucket Pipelines variable. For Git clone: git clone https://x-token-auth:$TOKEN@bitbucket.org/workspace/repo.git. For API calls: curl -H "Authorization: Bearer $TOKEN" https://api.bitbucket.org/2.0/.... Never commit tokens to your repository or bitbucket-pipelines.yml.

Common causes: (1) Using account password instead of App Password — password auth was deprecated in 2022. (2) App Password doesn't have the required permission scope (e.g., trying to push without Repositories: Write). (3) Token expired — OAuth 2.0 tokens expire; check if you need to refresh. (4) 2FA enabled but not using App Password — standard password prompts won't work with 2FA. (5) Wrong username — use your Bitbucket username (not email) for HTTP Basic auth.

Related tools

compare //

Bitbucket vs GitHub

compare //

GitLab vs GitHub

ci/cd //

CI/CD Pipeline Visualizer

git //

Git Workflow Analyzer

api //

API Gateway Analyzer

Bitbucket Auth Guide —App Passwords, OAuth, SSH & Tokens

Bitbucket Auth Guide —
App Passwords, OAuth, SSH & Tokens