Keys

This part of the API is the means by which you operate on your SSH/signing 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 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)

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

Inputs

  • None

Returns

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

For all possible errors, see CloudAPI HTTP Responses.

Error Code

Description

ResourceNotFound

If :login does not exist

CLI Command

triton key list

or

$ sdc-listkeys

Example Request

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

Example Response

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)

Retrieves the record for an individual key.

Inputs

  • None

Returns

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

For all possible errors, see CloudAPI HTTP Responses.

Error Code

Description

ResourceNotFound

If :login or :key does not exist

CLI Command

triton key get barbar

or

sdc-getkey barbar

Example Request

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

Example Response

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)

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

Inputs

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

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

For all possible errors, see 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

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

or

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

Example Request

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

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)

Deletes a single SSH key, by name or fingerprint.

Inputs

  • None

Returns

  • None

Errors

For all possible errors, see CloudAPI HTTP Responses.

Error Code

Description

ResourceNotFound

If :login or :key does not exist

CLI Command

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

Last updated