# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mnx.io/cloudapi/api-details/keys.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.