Cloud

Bitbucket Cloud / Reference / REST APIs

SSH

The SSH resource allows you to manage SSH keys.

Operations

GET/users/{selected_user}/ssh-keys POST/users/{selected_user}/ssh-keys GET/users/{selected_user}/ssh-keys/{key_id}PUT/users/{selected_user}/ssh-keys/{key_id}DEL/users/{selected_user}/ssh-keys/{key_id}

GET

List SSH keys

Returns a paginated list of the user's SSH public keys.

Scopes

OAuth 2.0 and Connect app scopes required:

account

API Token scopes required:

read:ssh-key:bitbucket

Request

Path parameters

selected_user

string

Required

Responses

A list of the SSH keys associated with the account.

application/json

Paginated SSH User Keys

A paginated list of SSH keys.

GET/users/{selected_user}/ssh-keys

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/users/{selected_user}/ssh-keys' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

{
  "page": 1,
  "pagelen": 10,
  "size": 1,
  "values": [
    {
      "comment": "user@myhost",
      "created_on": "2018-03-14T13:17:05.196003+00:00",
      "expires_on": null,
      "fingerprint": "w9tZSiFoZ8oXwS4ZSWrJopGxwvnPIewA6Mo4owAHPrI",
      "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY",
      "label": "",
      "last_used": "2018-03-20T13:18:05.196003+00:00",
      "links": {
        "self": {
          "href": "https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/b15b6026-9c02-4626-b4ad-b905f99f763a"
        }
      },
      "owner": {
        "display_name": "Mark Adams",
        "links": {
          "avatar": {
            "href": "https://bitbucket.org/account/markadams-atl/avatar/32/"
          },
          "html": {
            "href": "https://bitbucket.org/markadams-atl/"
          },
          "self": {
            "href": "https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}"
          }
        },
        "type": "user",
        "username": "markadams-atl",
        "nickname": "markadams-atl",
        "uuid": "{d7dd0e2d-3994-4a50-a9ee-d260b6cefdab}"
      },
      "type": "ssh_key",
      "uuid": "{b15b6026-9c02-4626-b4ad-b905f99f763a}"
    }
  ]
}

POST

Add a new SSH key

Adds a new SSH public key to the specified user account and returns the resulting key.

Example:


1
$ curl -X POST -H "Content-Type: application/json" -d '{"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY user@myhost"}' https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys

Scopes

OAuth 2.0 and Connect app scopes required:

account:write

API Token scopes required:

read:ssh-key:bitbucket, write:ssh-key:bitbucket

Request

Path parameters

selected_user

string

Required

Query parameters

expires_on

string

Request bodyapplication/json

The new SSH key object. Note that the username property has been deprecated due to privacy changes.

allOf [allOf [object, SSH Key], SSH Account Key]

object

Base type for most resource objects. It defines the common type element that identifies an object's type. It also identifies the element as Swagger's discriminator.

SSH Key

Base type for representing SSH public keys.

SSH Account Key

Represents an SSH public key for a user.

Responses

The newly created SSH key.

application/json

allOf [allOf [object, SSH Key], SSH Account Key]

object

Base type for most resource objects. It defines the common type element that identifies an object's type. It also identifies the element as Swagger's discriminator.

SSH Key

Base type for representing SSH public keys.

SSH Account Key

Represents an SSH public key for a user.

POST/users/{selected_user}/ssh-keys

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.bitbucket.org/2.0/users/{selected_user}/ssh-keys' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "<string>",
  "uuid": "<string>",
  "key": "<string>",
  "comment": "<string>",
  "label": "<string>",
  "created_on": "<string>",
  "last_used": "<string>",
  "links": {
    "self": {
      "href": "<string>",
      "name": "<string>"
    }
  },
  "owner": {
    "type": "<string>"
  },
  "expires_on": "<string>",
  "fingerprint": "<string>"
}'

201Response

{
  "comment": "user@myhost",
  "created_on": "2018-03-14T13:17:05.196003+00:00",
  "expires_on": null,
  "fingerprint": "w9tZSiFoZ8oXwS4ZSWrJopGxwvnPIewA6Mo4owAHPrI",
  "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY",
  "label": "",
  "last_used": "2018-03-20T13:18:05.196003+00:00",
  "links": {
    "self": {
      "href": "https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/b15b6026-9c02-4626-b4ad-b905f99f763a"
    }
  },
  "owner": {
    "display_name": "Mark Adams",
    "links": {
      "avatar": {
        "href": "https://bitbucket.org/account/markadams-atl/avatar/32/"
      },
      "html": {
        "href": "https://bitbucket.org/markadams-atl/"
      },
      "self": {
        "href": "https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}"
      }
    },
    "type": "user",
    "username": "markadams-atl",
    "nickname": "markadams-atl",
    "uuid": "{d7dd0e2d-3994-4a50-a9ee-d260b6cefdab}"
  },
  "type": "ssh_key",
  "uuid": "{b15b6026-9c02-4626-b4ad-b905f99f763a}"
}

GET

Get a SSH key

Returns a specific SSH public key belonging to a user.

Scopes

OAuth 2.0 and Connect app scopes required:

account

API Token scopes required:

read:ssh-key:bitbucket

Request

Path parameters

key_id

string

Required

selected_user

string

Required

Responses

The specific SSH key matching the user and UUID

application/json

allOf [allOf [object, SSH Key], SSH Account Key]

object

Base type for most resource objects. It defines the common type element that identifies an object's type. It also identifies the element as Swagger's discriminator.

SSH Key

Base type for representing SSH public keys.

SSH Account Key

Represents an SSH public key for a user.

GET/users/{selected_user}/ssh-keys/{key_id}

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/users/{selected_user}/ssh-keys/{key_id}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

{
  "comment": "user@myhost",
  "created_on": "2018-03-14T13:17:05.196003+00:00",
  "expires_on": null,
  "fingerprint": "w9tZSiFoZ8oXwS4ZSWrJopGxwvnPIewA6Mo4owAHPrI",
  "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY",
  "label": "",
  "last_used": "2018-03-20T13:18:05.196003+00:00",
  "links": {
    "self": {
      "href": "https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/b15b6026-9c02-4626-b4ad-b905f99f763a"
    }
  },
  "owner": {
    "display_name": "Mark Adams",
    "links": {
      "avatar": {
        "href": "https://bitbucket.org/account/markadams-atl/avatar/32/"
      },
      "html": {
        "href": "https://bitbucket.org/markadams-atl/"
      },
      "self": {
        "href": "https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}"
      }
    },
    "type": "user",
    "username": "markadams-atl",
    "nickname": "markadams-atl",
    "uuid": "{d7dd0e2d-3994-4a50-a9ee-d260b6cefdab}"
  },
  "type": "ssh_key",
  "uuid": "{b15b6026-9c02-4626-b4ad-b905f99f763a}"
}

PUT

Update a SSH key

Updates a specific SSH public key on a user's account

Note: Only the 'comment' field can be updated using this API. To modify the key or comment values, you must delete and add the key again.

Example:


1
$ curl -X PUT -H "Content-Type: application/json" -d '{"label": "Work key"}' https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/{b15b6026-9c02-4626-b4ad-b905f99f763a}

Scopes

OAuth 2.0 and Connect app scopes required:

account:write

API Token scopes required:

read:ssh-key:bitbucket, write:ssh-key:bitbucket

Request

Path parameters

key_id

string

Required

selected_user

string

Required

Request bodyapplication/json

The updated SSH key object

allOf [allOf [object, SSH Key], SSH Account Key]

object

Base type for most resource objects. It defines the common type element that identifies an object's type. It also identifies the element as Swagger's discriminator.

SSH Key

Base type for representing SSH public keys.

SSH Account Key

Represents an SSH public key for a user.

Responses

The newly updated SSH key.

application/json

allOf [allOf [object, SSH Key], SSH Account Key]

object

Base type for most resource objects. It defines the common type element that identifies an object's type. It also identifies the element as Swagger's discriminator.

SSH Key

Base type for representing SSH public keys.

SSH Account Key

Represents an SSH public key for a user.

PUT/users/{selected_user}/ssh-keys/{key_id}

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'https://api.bitbucket.org/2.0/users/{selected_user}/ssh-keys/{key_id}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "<string>",
  "uuid": "<string>",
  "key": "<string>",
  "comment": "<string>",
  "label": "<string>",
  "created_on": "<string>",
  "last_used": "<string>",
  "links": {
    "self": {
      "href": "<string>",
      "name": "<string>"
    }
  },
  "owner": {
    "type": "<string>"
  },
  "expires_on": "<string>",
  "fingerprint": "<string>"
}'

200Response

{
  "comment": "",
  "created_on": "2018-03-14T13:17:05.196003+00:00",
  "expires_on": null,
  "fingerprint": "w9tZSiFoZ8oXwS4ZSWrJopGxwvnPIewA6Mo4owAHPrI",
  "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY",
  "label": "Work key",
  "last_used": "2018-03-20T13:18:05.196003+00:00",
  "links": {
    "self": {
      "href": "https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/b15b6026-9c02-4626-b4ad-b905f99f763a"
    }
  },
  "owner": {
    "display_name": "Mark Adams",
    "links": {
      "avatar": {
        "href": "https://bitbucket.org/account/markadams-atl/avatar/32/"
      },
      "html": {
        "href": "https://bitbucket.org/markadams-atl/"
      },
      "self": {
        "href": "https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}"
      }
    },
    "type": "user",
    "username": "markadams-atl",
    "nickname": "markadams-atl",
    "uuid": "{d7dd0e2d-3994-4a50-a9ee-d260b6cefdab}"
  },
  "type": "ssh_key",
  "uuid": "{b15b6026-9c02-4626-b4ad-b905f99f763a}"
}

DEL

Delete a SSH key

Deletes a specific SSH public key from a user's account.

Scopes

OAuth 2.0 and Connect app scopes required:

account:write

API Token scopes required:

delete:ssh-key:bitbucket

Request

Path parameters

key_id

string

Required

selected_user

string

Required

Responses

The key has been deleted

DEL/users/{selected_user}/ssh-keys/{key_id}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request DELETE \
  --url 'https://api.bitbucket.org/2.0/users/{selected_user}/ssh-keys/{key_id}' \
  --header 'Authorization: Bearer <access_token>'