Access keys

Add access keys to your Bitbucket Cloud repositories to allow a user or service to authenticate when pulling or cloning a repository over SSH. For example, you may want to use an access keys to authenticate with Bitbucket when a build server checks out and tests your code. 

An access key has the following features and limitations:

  • Grant read-only access to a public or private repository.
  • Don't require additional users on your plan.
  • Can be added to multiple repositories.
  • Can't also be associated with an account.
  • Don't require a passphrase when used for automated processes.

Before you can add an access key to a repository, you'll need to generate a unique SSH key just as you would for your individual account.

Step 1. Generate an SSH key

For detailed information on the SSH protocol and generating keys, see Set up an SSH key.

On macOS / Linux:

  1. From the terminal, enter ssh-keygen at the command line.
    The command prompts you for a file to save the key in:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/Users/emmap1/.ssh/id_rsa):
  2. Press the Enter or Return key to accept the default location.

    We recommend you keep the default key name unless you have a reason to change it.

    To create a key with a name or path other than the default, specify the full path to the key. For example, to create a key called my-new-ssh-key, enter a path like the one shown at the prompt:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/Users/emmap1/.ssh/id_rsa): /Users/emmap1/.ssh/my-new-ssh-key
  3. Enter and re-enter a passphrase when prompted.
    The command creates your default identity with its public and private keys. The whole interaction will look similar to the following:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/Users/emmap1/.ssh/id_rsa):
    Created directory '/Users/emmap1/.ssh'.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /Users/emmap1/.ssh/id_rsa.
    Your public key has been saved in /Users/emmap1/.ssh/id_rsa.pub.
    The key fingerprint is:
    4c:80:61:2c:00:3f:9d:dc:08:41:2e:c0:cf:b9:17:69 emmap1@myhost.local
    The key's randomart image is:
    +--[ RSA 2048]----+
    |*o+ooo.          |
    |.+.=o+ .         |
    |. *.* o .        |
    | . = E o         |
    |    o . S        |
    |   . .           |
    |     .           |
    |                 |
    |                 |
    +-----------------+
  4. List the contents of ~/.ssh to view the key files.

    $ ls ~/.ssh
    id_rsa id_rsa.pub

    The command displays two files, one for the public key (for example id_rsa.pub) and one for the private key (for example, id_rsa).

On Windows:

  1. From the command line, enter ssh-keygen.

    For Windows 7 or earlier

    You can only enter ssh-keygen into the Git Bash window. It won't work in the Command prompt.

    The command prompts you for a file to save the key in:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/c/Users/emmap1/.ssh/id_rsa):
  2. Press enter to accept the default key and path, /c/Users/<username>/.ssh/id_rsa.

    We recommend you keep the default key name unless you have a reason to change it.

    To create a key with a name or path other than the default, specify the full path to the key. For example, to create a key called my-new-ssh-key, you would enter the Windows path, shown here:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/c/Users/emmap1/.ssh/id_rsa): c:\Users\emmap1\.ssh\my-new-ssh-key
  3. Enter and re-enter a passphrase when prompted.

    The command creates your default identity with its public and private keys. The whole interaction looks similar to this:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/c/Users/emmap1/.ssh/id_rsa):
    Created directory '/c/Users/emmap1/.ssh'.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /c/Users/emmap1/.ssh/id_rsa.
    Your public key has been saved in /c/Users/emmap1/.ssh/id_rsa.pub.
    The key fingerprint is: e7:94:d1:a3:02:ee:38:6e:a4:5e:26:a3:a9:f4:95:d4 emmap1@EMMA-PC
  4. List the contents of .ssh to view the key files.

    You should see something like the following:

    $ dir .ssh
    id_rsa id_rsa.pub

    The command displays two files, one for the public key (for example id_rsa.pub) and one for the private key (for example, id_rsa).

Step 2. Add the private key

For the access key to work with your service, you'll need to add the private key to its system. Where you add the private key depends on the service, but you'll typically add it from its authentication or credentials section. You may need to add the private key to more than one place. For example, if you're using Bamboo to build and test your project, you should add the key to each agent.

To authenticate with an access key as a user, add the SSH key to the ssh-agent locally, just as you would when you're adding the key to your individual account. See Set up an SSH key for more details.

Step 3. Add the public key to your repository

To add an access key to a repository:

  1. In a terminal or Command Prompt, log in to the server where the key is located. Copy the contents of the public key to the clipboard:

    Linux

    $ cat ~/.ssh/<public_key_file>

    Mac OS X

    $ pbcopy < ~/.ssh/<public_key_file>

    Windows

    $ cd <userprofile>/.ssh
    $ clip < <public_key_file>
  2. From Bitbucket, go to the repository and click Settings.
  3. Click Access keys from the left menu.
  4. Press Add key.
  5. From the Add SSH key dialog, enter a Label and paste the public key from the clipboard.
  6. Press Add key. Bitbucket notifies you by email that you added a key to your repository.

If you are using your key for a build system, it is a good idea to confirm the key is working correctly from the service or build server. For example, you can test it by manually cloning the repository using SSH, just as you would normally clone a repository. If you have trouble using your key, see Troubleshoot SSH issues.

Edit an access key

After you add a key, you can edit the key's Label but not the key itself. For security purposes, you need to delete and re-add the key to change the key's contents.

Last modified on Jul 12, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.