API

SSH Keys

To manage the SSH keys for an account that are used for logging in to instances, there are a set of APIs for listing the SSH public keys currently stored, as well as adding and removing them by name.

Uploading an SSH key

Uploading an SSH public key is done by sending a POST request to the https://api.civo.com/v2/sshkeys resource.

Request

The following parameter(s) should be sent along with the request:

Name Description
name (required) a string that will be the reference for the SSH key.
public_key (required) a string containing the SSH public key.

Response

The response from the server will just be a confirmation of success and the ID of the new key.

{
  "result": "success",
  "id": "730c960f-a51f-44e5-9c21-bd135d015d12"
}

Example of uploading an SSH key

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/sshkeys \
  -d name=default&public_key=ssh-dss%20AAAAB3N...
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/sshkeys',
  {
    form: {
      name: 'default',
      public_key: 'ssh-dss AAAAB3N...'
    }
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/sshkeys', 'name=default&public_key=ssh-dss%20AAAAB3N...', headers)

Listing the SSH keys

Listing the SSH public keys is done by sending a GET request to the https://api.civo.com/v2/sshkeys resource.

Request

This request doesn't take any parameters.

Response

The response from the server will be a list of the SSH keys known for the current account holder.

[
  {
    "id": "730c960f-a51f-44e5-9c21-bd135d015d12",
    "name": "default",
    "fingerprint": "SHA256:181210f8f9c779c26da1d9b2075bde0127302ee0e3fca38c9a83f5b1dd8e5d3b"
  }
]

Example of listing the SSH keys

curl -H "Authorization: bearer 12345" \
  https://api.civo.com/v2/sshkeys
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/sshkeys',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/sshkeys', '', headers)

Retrieving an SSH key

A single SSH key's details are available by sending a GET request to https://api.civo.com/v2/sshkeys/:id.

Request

This request requires only the ID parameter in the URL.

Response

The response is a JSON object that describes the details for the SSH key.

{
  "id": "730c960f-a51f-44e5-9c21-bd135d015d12",
  "name": "default",
  "fingerprint": "SHA256:181210f8f9c779c26da1d9b2075bde0127302ee0e3fca38c9a83f5b1dd8e5d3b"
}

Example of retrieving an SSH key

curl -H "Authorization: bearer 12345" \
  https://api.civo.com/v2/sshkeys/730c960f-a51f-44e5-9c21-bd135d015d12
    
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/sshkeys/730c960f-a51f-44e5-9c21-bd135d015d12',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/sshkeys/730c960f-a51f-44e5-9c21-bd135d015d12', headers)

Updating an SSH key

Updating an SSH key only allows you to update the name and the request is a PUT request to https://api.civo.com/v2/sshkeys/:id.

Request

The following parameter(s) should be sent along with the request:

Name Description
name (required) a string that will be the reference for the SSH key.

Response

The response from the server will be the updated SSH key.

[
  {
    "id": "730c960f-a51f-44e5-9c21-bd135d015d12",
    "name": "updated-name",
    "fingerprint": "SHA256:181210f8f9c779c26da1d9b2075bde0127302ee0e3fca38c9a83f5b1dd8e5d3b"
  }
]

Example of updating an SSH key

curl -X PUT -H "Authorization: bearer 12345" \
  https://api.civo.com/v2/sshkeys/7b378c32-6695-48b5-9e41-b95519611712 \
  -d name=updated-name
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.put(
  'https://api.civo.com/v2/sshkeys/7b378c32-6695-48b5-9e41-b95519611712',
  {name: "updated-name"},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.put('/v2/sshkeys/7b378c32-6695-48b5-9e41-b95519611712', 'name=updated-name', headers)

Removing an SSH key

The account holder can remove an SSH key attached to their account. However, this only removes it from selection when creating instances, it doesn't remove it from previously created instances. This should be definitely confirmed by the user before any API call is made because doing so will immediately remove the SSH key. This action is performed by sending a DELETE request to https://api.civo.com/v2/sshkeys/:id

Request

This request doesn't take any parameters other than the key name in the URL.

Response

The response from the server will be a JSON block. The response will include a result field and the HTTP status will be 200 OK.

{
  "result": "success"
}

Example of removing an SSH key

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/sshkeys/730c960f-a51f-44e5-9c21-bd135d015d12
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.del(
  'https://api.civo.com/v2/sshkeys/730c960f-a51f-44e5-9c21-bd135d015d12',
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/sshkeys/730c960f-a51f-44e5-9c21-bd135d015d12', headers)