Skip to main content

Import Key for SSH Access

To gain secure shell (SSH) access to your virtual machines, begin by creating and importing a key pair: the public key is saved in Infrahub API/Hyperstack to be used with VMs for SSH access, and the private key is downloaded to be used with an SSH client.

Follow the instructions below to:

  1. Create a key pair
  2. Import an SSH key pair
  3. Enable SSH access to your virtual machine

1. Create a key pair

To create a key pair:

  1. Open Terminal.

  2. Use the ssh-keygen command to create a new key:

  3. After you run the command, you will be asked to specify the names of files where the keys will be saved and enter the password for the private key. Press Enter to use the default name. The key pair will be created in the ~/.ssh directory.

  4. Your public key will be saved with a .pub extension. The private key will be in the location you specified.

    Public key: /path/to/your/

    Private key: /path/to/your/key

  5. Copy the public key from the <key_name>.pub file using any text editor, such as Notepad. Please note that the key must be written as a single line (no returns or line breaks).


Never share your private SSH key. Only the public key needs to be imported to access your virtual machines.

Next, use the public key you copied to your clipboard in the public_key field when making the API request to import an SSH key pair.

2. Importing an SSH key pair


To import a key pair, use the POST /core/keypairs endpoint with the completed request body as shown in the request below.

In the body of the request include the following fields:

  1. The name field containing the name of your choosing for the SSH key pair you are creating.

  2. The environment_name field with the name of the environment within which the SSH key will be stored.

  3. The public_key field with the public key that you just saved to clipboard in the previous step.


Save the name of your new key pair, as this will be necessary to create your virtual machine.

Example request
curl -X POST ""
-H "api_key: YOUR API KEY"
-H "Content-Type: application/json"
-d '{
"name": "example-key-name",
"environment_name": "example-environment-name",
"public_key": "ssh-ed25519 AAAAAC3NzaC1lZDINTE5AAAAIHna64ksd7dXJKhsf8xKkXf+s9djdkx97Hs6Dfn [email protected]"
"status": true,
"message": "Keypair is imported successfully",
"keypair": {
"id": 3,
"name": "example-key-name",
"environment": "example-environment-nam",
"public_key": "ssh-ed25519 AAAAAC3NzaC1lZDINTE5AAAAIHna64ksd7dXJKhsf8xKkXf+s9djdkx97Hs6Dfn [email protected]",
"fingerprint": "23:64:b2:8e:89:4b:be:21:a6:51:22:d8:80:fb:e2:22",
"created_at": "1970-01-01T00:00:00.000Z"

3. Enable incoming SSH traffic to your virtual machine

To enable incoming traffic to your virtual machine, you must create a firewall rule, this can be done using Hyperstack or the Infrahub API.

Send a request to /core/virtual-machines/{virtual-machine-id}/sg-rules endpoint replacing virtual-machine-id in the path with the ID of the virtual machine for which you want to enable SSH access, and complete the body of the request as specified below.

  • Include the integer ID of the virtual machine that this firewall rule is being attached to in the path of the request as follows:
    • /core/virtual-machines/{VM ID HERE}/sg-rules
  • Complete the request body with the following fields and values:

    Field NameField InputDescription
    remote_ip_prefix0.0.0.0/0Allows traffic from any source IP address.
    directioningressDesignates that the firewall rule is for incoming traffic.
    ethertypeIPv4Indicates the use of Internet Protocol version 4.
    protocolicmpSpecifies the use of Internet Control Message Protocol.
    port_range_min22Specifies the minimum port value for SSH.
    port_range_max22Specifies the maximum port value for SSH.
curl -X POST{virtual-machine-id}/sg-rules \
-H "accept: application/json" \
-H "api_key: YOUR API KEY" \
-d '{
"remote_ip_prefix": "",
"direction": "ingress",
"ethertype": "IPv4",
"protocol": "tcp",
"port_range_min": 22,
"port_range_max": 22

To authenticate Infrahub API requests, add an authorization header to your API request that contains an API Key as follows:

  -H "api_key: YOUR API KEY"

Now that you have successfully imported the SSH key, let's move on to launching a virtual machine.

Back to top