How to use different SSH keys for multiple Bitbucket accounts

Your support helps keep this blog running! Secure payments via Paypal and Stripe.

Bitbucket Cloud officially disabled the use of Basic authentication (using your account password directly) with the Bitbucket API and Git over HTTPS on March 1, 2022.

Therefore, there are two recommended methods to access Bitbucket Cloud repositories from your computer:

1. App Passwords: These are unique, generated passwords that provide access to your Bitbucket account without exposing your main account password. They are specifically designed for use with tools, scripts, and basic authentication for Git and API access.
2. SSH Keys: This is a more secure and convenient method for Git operations, as it uses cryptographic keys for authentication, eliminating the need to enter a password for every push or pull.

This post will cover how to use the SSH key method to handle multiple Bitbucket accounts with separate SSH keys.

Here are the essential steps to get your SSH keys working with Bitbucket Cloud:

1. Generate a strong key pair (we’ll use ed25519, which is now preferred over RSA).
2. Add each public key to its respective Bitbucket account.
3. Configure your local SSH client so that each account uses the correct key automatically.
4. Clone new repos or update existing remotes to use your SSH “Host” aliases.

Prerequisites

• Git installed (≥2.x on Windows, ≥2.x on Unix).
• Your shell’s SSH client (OpenSSH) is available—in Git for Windows, Git Bash includes one; on macOS and most Linux distros, it’s built-in.
• A Bitbucket Cloud account (app passwords still required for HTTPS, but we’re using SSH here).

SSH Directory Structure by Platform

Before generating the SSH key, I will show you where the SSH key, config, and known_hosts files are stored on your computer.

The SSH client stores keys, configs, and known hosts in a hidden .ssh directory located inside the user’s home directory:

Linux & macOS

• User SSH directory: ~/.ssh/
• Full paths:

~/.ssh/id_ed25519                  # Private SSH key
~/.ssh/id_ed25519.pub              # Public SSH key
~/.ssh/config                      # Per-host SSH configuration
~/.ssh/known_hosts                 # Host fingerprints Bitbucket & others
~/.ssh/authorized_keys             # (Usually on remote servers for login access)

Windows (PowerShell or Git Bash)

Windows uses a different home directory depending on the shell:

• Git Bash: /c/Users/YourName/.ssh/
• PowerShell or CMD: C:\Users\YourName\.ssh\

Full paths (PowerShell):

C:\Users\YourName\.ssh\id_ed25519          # Private key
C:\Users\YourName\.ssh\id_ed25519.pub      # Public key
C:\Users\YourName\.ssh\config              # SSH config file (optional)
C:\Users\YourName\.ssh\known_hosts         # Auto-generated on first connection

Notes

Permissions matter (especially on Unix):

• ~/.ssh: 700 (drwx——)
• id_ed25519: 600 (-rw——-)
• config: 600 (-rw——-)

You can safely create or edit the config file yourself to define aliases for each Bitbucket account.

Generate a unique ed25519 key pair per account

By convention, we’ll name our keys to indicate the account:

# Personal account
ssh-keygen -t ed25519 \
  -C "your_email@example.com" \
  -f ~/.ssh/id_ed25519_bitbucket_personal

# Work/client account
ssh-keygen -t ed25519 \
  -C "your_work_email@company.com" \
  -f ~/.ssh/id_ed25519_bitbucket_work

• -C adds a comment (your email) to the public key for easy identification.
• -f specifies the file: ~/.ssh/id_ed25519_bitbucket_….
• You’ll be prompted for a passphrase—highly recommended.

On Windows PowerShell, you can run the same commands if you have the OpenSSH client installed; on Git Bash, they work out of the box.

Add each public key to its Bitbucket account

• Log in to your Bitbucket Cloud account.
• Click your avatar → Personal settings → SSH keys → Add key.
• Open the *.pub file (e.g. ~/.ssh/id_ed25519_bitbucket_personal.pub) in a text editor, copy its entire contents, and paste into the Key field.
• Give it a descriptive Label (e.g., “Personal laptop key”) and Save.
• Repeat for your second account and its id_ed25519_bitbucket_work.pub.

Ensure your SSH agent is running and keys are loaded

macOS / Linux

# start ssh-agent (if not already running)
eval "$(ssh-agent -s)"

# add both private keys
ssh-add ~/.ssh/id_ed25519_bitbucket_personal
ssh-add ~/.ssh/id_ed25519_bitbucket_work

To load keys automatically on login:

• macOS: add the ssh-add … lines to your ~/.ssh/config with AddKeysToAgent yes, or use the Keychain (ssh-add -K …).
• Linux: add the commands to your ~/.profile or your desktop‐environment’s “Startup Applications.”

Windows (Git Bash or PowerShell)

If using Git Bash, the above Unix commands work. If using PowerShell with the built-in OpenSSH:

# start agent
Start-Service ssh-agent
Set-Service -StartupType Automatic -Name ssh-agent

# add keys
ssh-add $HOME\.ssh\id_ed25519_bitbucket_personal
ssh-add $HOME\.ssh\id_ed25519_bitbucket_work

Configure ~/.ssh/config with Host aliases

Create or edit ~/.ssh/config (permissions 600) and add one block per account:

# Personal Bitbucket account
Host bitbucket-personal
    HostName bitbucket.org
    User     git
    IdentityFile ~/.ssh/id_ed25519_bitbucket_personal
    IdentitiesOnly yes
    AddKeysToAgent yes

# Work/Client Bitbucket account
Host bitbucket-work
    HostName bitbucket.org
    User     git
    IdentityFile ~/.ssh/id_ed25519_bitbucket_work
    IdentitiesOnly yes
    AddKeysToAgent yes

• Host is a nickname you’ll use in your Git URLs.
• HostName must be bitbucket.org.
• IdentitiesOnly yes prevents SSH from trying other keys.
• AddKeysToAgent yes automatically loads the key into your agent when you connect.

Clone new repos with the correct key

Instead of the usual:

git clone git@bitbucket.org:yourPersonalWorkspace/repo.git

git clone git@bitbucket.org:yourWorkWorkspace/repo.git

Use your Host alias:

# Personal account
git clone git@bitbucket-personal:yourPersonalWorkspace/your-repo.git

# Work account
git clone git@bitbucket-work:yourWorkWorkspace/your-repo.git

SSH will see “bitbucket-personal” or “bitbucket-work” in place of “bitbucket.org,” pick the right key, and connect you to the right account.

Switch an existing repo to SSH + Host alias

If you already cloned via HTTPS—or via the default SSH host—just update the remote URL:

git remote set-url origin git@bitbucket-personal:yourPersonalWorkspace/your-repo.git
# or
git remote set-url origin git@bitbucket-work:yourWorkWorkspace/your-repo.git

Verify:

git remote -v
# origin  git@bitbucket-personal:… (fetch)
# origin  git@bitbucket-personal:… (push)

Bitbucket Cloud SSH Host Keys changed on June 20, 2023

When connecting to bitbucket.org via SSH, if you see the below error, please update the Bitbucket host key.

Offending RSA key in /Users/macmagician/.ssh/known_hosts:1
Host key for bitbucket.org has changed and you have requested strict checking.
Host key verification failed.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

Testing your SSH connection

This confirms SSH key usage and host alias config:

ssh -T git@bitbucket-personal
ssh -T git@bitbucket-work

If everything is set up correctly, Bitbucket will respond with:

logged in as your_username.

You can use git or hg to connect to Bitbucket. Shell access is disabled.

If you get a Permission denied (publickey) error, something is wrong with the SSH key setup—check that the right key is loaded into the agent and your ~/.ssh/config is correctly configured.

Verbose debugging (SSH only)

If things aren’t working, add -v to see what’s happening:

ssh -vT git@bitbucket-personal

This will print verbose output of which key is being offered and whether it’s accepted. Look for lines like:

Offering public key: ~/.ssh/id_ed25519_bitbucket_personal
Authenticated to bitbucket.org ([IP]:22) using "publickey".

Troubleshooting

• “Permission denied (publickey)”
  • Ensure the key is added to your agent (ssh-add -l).
  • Check ~/.ssh/config for typos in Host or IdentityFile.
  • Confirm you pasted the correct public key into the right Bitbucket account.
• First-time host key warning
  “The authenticity of host ‘bitbucket.org (IP…)’ can’t be established…”
  Just type yes to add Bitbucket’s host key to your known_hosts.
• No more passphrase prompts?
  If you’ve loaded your key into the agent with AddKeysToAgent yes, you’ll only type your passphrase once per session.

Adding a New Remote Repository

To connect your local project to a new repository on Bitbucket, follow these steps:

1. Initialize Git: Open your project folder in VS Code and use the command git init in the terminal to create the .git file.
2. Prepare Files: Create a .gitignore file if needed, then commit these initial changes.
3. Create Remote Repository: On Bitbucket, create a new repository. You can choose to use the default branch name, such as main, or a different one. It’s best not to create a README or .gitignore file on Bitbucket if you already have them locally.
4. Connect to Remote: In your VS Code terminal, add the remote repository URL. Make sure the hostname matches the one in your config file. Below is a command for adding the remote repository.
   git remote add origin git@bitbucket-personal:yourPersonalWorkspace/your-new-repo.git
5. Verify Connection: Use git remote -v to confirm that the fetch and push URLs are correct.
6. Push to Remote: Push your local branch to the new remote repository. If your local branch is called main, the command would be git push -u origin main If you are prompted for a passphrase, enter it.

After these steps, your source code should appear in the new repository on Bitbucket.

Summary

By generating one ed25519 key pair per account, adding them into your SSH agent, and defining clear Host aliases in ~/.ssh/config, you can seamlessly manage multiple Bitbucket accounts on the same machine—no more juggling or overwriting id_rsa files. Enjoy secure, password-free pushes and pulls!

Your support helps keep this blog running! Secure payments via Paypal and Stripe.