# Keys

This part of the API is the means by which you operate on your SSH/signing keys. These keys are needed in order to login to instances over SSH, as well as signing requests to this API (see the HTTP Signature Authentication Scheme outlined in [Appendix B](https://apidocs.joyent.com/cloudapi/#appendix-b-http-signature-authentication) for more details).

Currently CloudAPI supports uploads of public keys in the OpenSSH format.

Note that while it's possible to provide a `name` attribute for an SSH key in order to use it as a human-friendly alias, this attribute's presence is optional. When it's not provided, the ssh key fingerprint will be used as the `name` instead.

Keys can optionally be submitted along with a hardware attestation certificate signed by a trusted hardware manufacturer, which will be validated and processed. Keys generated in hardware devices which require some form of multi-factor authentication to sign requests (e.g. the device requires a PIN or Touch input) are marked by this mechanism and may be specially treated by Triton and Manta as providing a kind of 2-factor authentication (depending on administrator policy).

For the following routes, the parameter placeholder `:key` can be replaced with with either the key's `name` or its `fingerprint`. It's strongly recommended to use `fingerprint` when possible, since the `name` attribute does not have any uniqueness constraints.

### ListKeys (GET /:login/keys) <a href="#listkeys" id="listkeys"></a>

Lists all public keys we have on record for the specified account.

#### Inputs <a href="#inputs-4" id="inputs-4"></a>

* None

#### Returns <a href="#returns-4" id="returns-4"></a>

Array of key objects. Each key object has the following fields:

| **Field**   | **Type**       | **Description**                                            |
| ----------- | -------------- | ---------------------------------------------------------- |
| name        | String         | Name for this key                                          |
| fingerprint | String         | Key fingerprint                                            |
| key         | String         | Public key in OpenSSH format                               |
| attested    | Boolean        | Indicates if the key has a hardware device attestation     |
| multifactor | Array\[String] | Lists any additional factors required to use (if attested) |

Possible `multifactor` values:

| **Value** | **Meaning**                                                                       |
| --------- | --------------------------------------------------------------------------------- |
| pin       | Input of a PIN or password is required for key use                                |
| touch     | Touch input (not authenticated -- i.e. not a fingerprint) is required for key use |

#### Errors <a href="#errors-4" id="errors-4"></a>

For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).

| **Error Code**   | **Description**            |
| ---------------- | -------------------------- |
| ResourceNotFound | If `:login` does not exist |

#### CLI Command <a href="#cli-command-3" id="cli-command-3"></a>

```
triton key list

or

$ sdc-listkeys
```

#### Example Request <a href="#example-request-4" id="example-request-4"></a>

```
GET /my/keys HTTP/1.1
Host: api.example.com
Authorization: ...
Accept: application/json
Api-Version: ~8
```

#### Example Response <a href="#example-response-4" id="example-response-4"></a>

```
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 832
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: u4xmk+MgKzzIvrRt09k4sg==
Date: Tue, 22 Dec 2015 12:23:12 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: c44e2000-a8a6-11e5-9030-479dc847c4b2
Response-Time: 1041

[
  {
    "name": "barbar",
    "fingerprint": "03:7f:8e:ef:da:3d:3b:9e:a4:82:67:71:8c:35:2c:aa",
    "key": "<...>"
  }
]
```

### GetKey (GET /:login/keys/:key) <a href="#getkey" id="getkey"></a>

Retrieves the record for an individual key.

#### Inputs <a href="#inputs-5" id="inputs-5"></a>

* None

#### Returns <a href="#returns-5" id="returns-5"></a>

| **Field**   | **Type**       | **Description**                                            |
| ----------- | -------------- | ---------------------------------------------------------- |
| name        | String         | Name for this key                                          |
| fingerprint | String         | Key fingerprint                                            |
| key         | String         | OpenSSH formatted public key                               |
| attested    | Boolean        | Indicates if the key has a hardware device attestation     |
| multifactor | Array\[String] | Lists any additional factors required to use (if attested) |

Possible `multifactor` values:

| **Value** | **Meaning**                                                                       |
| --------- | --------------------------------------------------------------------------------- |
| pin       | Input of a PIN or password is required for key use                                |
| touch     | Touch input (not authenticated -- i.e. not a fingerprint) is required for key use |

#### Errors <a href="#errors-5" id="errors-5"></a>

For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).

| **Error Code**   | **Description**                      |
| ---------------- | ------------------------------------ |
| ResourceNotFound | If `:login` or `:key` does not exist |

#### CLI Command <a href="#cli-command-4" id="cli-command-4"></a>

```
triton key get barbar
```

or

```
sdc-getkey barbar
```

#### Example Request <a href="#example-request-5" id="example-request-5"></a>

```
GET /my/keys/barbar HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Api-Version: ~8
```

#### Example Response <a href="#example-response-5" id="example-response-5"></a>

```
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 830
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET, HEAD, DELETE
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: p8gjrCZqMiZbD15TA9ymEQ==
Date: Tue, 22 Dec 2015 13:26:17 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 94423be0-a8af-11e5-a95f-e74285cfeb5b
Response-Time: 999

{
  "name": "barbar",
  "fingerprint": "03:7f:8e:ef:da:3d:3b:9e:a4:82:67:71:8c:35:2c:aa",
  "key": "<...>",
  "attested": true,
  "multifactor": ["pin"]
}
```

### CreateKey (POST /:login/keys) <a href="#createkey" id="createkey"></a>

Uploads a new OpenSSH key to Triton for use in HTTP signing and SSH.

#### Inputs <a href="#inputs-6" id="inputs-6"></a>

| **Field**   | **Type**        | **Description**                        |
| ----------- | --------------- | -------------------------------------- |
| name        | String          | Name for this key (optional)           |
| key         | String          | OpenSSH formatted public key           |
| attestation | Array of String | PEM formatted attestation certificates |

#### Returns <a href="#returns-6" id="returns-6"></a>

| **Field**   | **Type**       | **Description**                                            |
| ----------- | -------------- | ---------------------------------------------------------- |
| name        | String         | Name for this key                                          |
| fingerprint | String         | Key fingerprint                                            |
| key         | String         | OpenSSH formatted public key                               |
| attested    | Boolean        | Indicates if the key has a hardware device attestation     |
| multifactor | Array\[String] | Lists any additional factors required to use (if attested) |

#### Errors <a href="#errors-6" id="errors-6"></a>

For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).

| **Error Code**   | **Description**                         |
| ---------------- | --------------------------------------- |
| InvalidArgument  | If name or key is invalid (usually key) |
| MissingParameter | If you didn't send a key                |
| ResourceNotFound | If `:login` does not exist              |

#### CLI Command <a href="#cli-command-5" id="cli-command-5"></a>

```
triton key add --name=barbardos ~/.ssh/id_rsa.pub
```

or

```
sdc-createkey --name=barbardos ~/.ssh/id_rsa.pub
```

#### Example Request <a href="#example-request-6" id="example-request-6"></a>

```
POST /my/keys HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 455
Content-Type: application/json
Api-Version: ~8

{
  "name": "barbardos",
  "fingerprint": "03:7f:8e:ef:da:3d:3b:9e:a4:82:67:71:8c:35:2c:aa",
  "key": "ssh-rsa AAA..."
}
```

#### Example Response <a href="#example-response-6" id="example-response-6"></a>

```
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 830
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET, HEAD, DELETE
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: p8gjrCZqMiZbD15TA9ymEQ==
Date: Tue, 22 Dec 2015 13:26:17 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 94423be0-a8af-11e5-a95f-e74285cfeb5b
Response-Time: 999

{
  "name": "barbardos",
  "fingerprint": "03:7f:8e:ef:da:3d:3b:9e:a4:82:67:71:8c:35:2c:aa",
  "key": "<...>"
}
```

### DeleteKey (DELETE /:login/keys/:key) <a href="#deletekey" id="deletekey"></a>

Deletes a single SSH key, by name or fingerprint.

#### Inputs <a href="#inputs-7" id="inputs-7"></a>

* None

#### Returns <a href="#returns-7" id="returns-7"></a>

* None

#### Errors <a href="#errors-7" id="errors-7"></a>

For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).

| **Error Code**   | **Description**                      |
| ---------------- | ------------------------------------ |
| ResourceNotFound | If `:login` or `:key` does not exist |

#### CLI Command <a href="#cli-command-6" id="cli-command-6"></a>

```
triton key delete barbados
```

or

```
sdc-deletekey barbados
```

**Example Request**

```
DELETE /my/keys/barbardos HTTP/1.1
Host: api.example.com
Accept: application/json
Api-Version: ~8
Content-Length: 0
```

**Example Response**

```
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET, HEAD, DELETE
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Tue, 22 Dec 2015 13:31:43 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 5677a420-a8b0-11e5-8702-0daf2c627de5
Response-Time: 829
```