Generate, upload, and manage SSH keys

SSH (Secure Shell) lets you securely connect to and administer your virtual machines (VMs) on STACKIT. Instead of a password, SSH uses a key pair for authentication:

• The private key stays on your computer. Never share it with anyone.
• The public key is stored in your STACKIT user account. When you create a VM, STACKIT adds the public key to the VM, so you can log in with the matching private key.

SSH keys are stored per user account. They are independent of the customer account and are available in all projects you have access to.

This guide shows you how to:

1. Generate an SSH key pair on your computer.
2. Upload the public key to your STACKIT user account.
3. List your SSH keys and compare them with your local keys.
4. Manage your SSH keys in the STACKIT Portal.

Generate an SSH key pair

If you already have an SSH key pair, for example ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub, you can skip this step and upload the existing public key.

We recommend the key type Ed25519. It is secure, fast, and produces short keys. Use RSA with 4096 bits only if a tool you use doesn’t support Ed25519.

Linux and macOS

1. Open a terminal.

2. Generate a new key pair. Replace the comment with a label that helps you identify the key, for example your email address or the name of your computer:

   ssh-keygen -t ed25519 -C "your_email@example.com"

   If you need an RSA key instead, use ssh-keygen -t rsa -b 4096 -C "your_email@example.com".

3. When prompted for a file location, press Enter to accept the default path (~/.ssh/id_ed25519), or enter a different path.

   Enter file in which to save the key (/home/you/.ssh/id_ed25519):

4. Enter a secure passphrase and repeat it. The passphrase encrypts your private key on disk, so it can’t be used if somebody gets hold of the file.

   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:

5. Display the public key:

   cat ~/.ssh/id_ed25519.pub

   The output is a single line similar to the following. You need this line when you upload the key to STACKIT.

   ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q your_email@example.com

Windows

Windows 10 (version 1809 and later) and Windows 11 include the OpenSSH client, so you don’t need to install additional software.

1. Open PowerShell or Windows Terminal.

2. Generate a new key pair. Replace the comment with a label that helps you identify the key, for example your email address or the name of your computer:

   ssh-keygen -t ed25519 -C "your_email@example.com"

3. When prompted for a file location, press Enter to accept the default path (C:\Users\<username>\.ssh\id_ed25519), or enter a different path.

4. Enter a secure passphrase and repeat it. The passphrase encrypts your private key on disk, so it can’t be used if somebody gets hold of the file.

5. Display the public key:

   Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub

   The output is a single line that starts with ssh-ed25519. You need this line when you upload the key to STACKIT.

If you prefer PuTTY, you can generate the key pair with PuTTYgen: select EdDSA (Ed25519) or RSA with 4096 bits, select Generate and enter a passphrase. Save the private key with Save private key. For the upload to STACKIT, copy the public key from the field Public key for pasting into OpenSSH authorized_keys file. Don’t use the file created by Save public key, because it isn’t in the OpenSSH format.

Optional: Add the key to the SSH agent

The SSH agent keeps your unlocked private key in memory, so you don’t need to enter the passphrase every time you connect.

Linux and macOS

1. Start the SSH agent in the background:

   eval "$(ssh-agent -s)"

2. Add your private key to the agent and enter your passphrase:

   ssh-add ~/.ssh/id_ed25519

3. macOS only: To load the key automatically and store the passphrase in your keychain, add the following to the file ~/.ssh/config. Create the file if it doesn’t exist.

   Host *
     AddKeysToAgent yes
     UseKeychain yes
     IdentityFile ~/.ssh/id_ed25519

   Then add the key once with ssh-add --apple-use-keychain ~/.ssh/id_ed25519.

Windows

1. Open PowerShell as administrator and start the SSH agent service. Set it to start automatically:

   Get-Service ssh-agent | Set-Service -StartupType Automatic
   Start-Service ssh-agent

2. In a regular PowerShell session, add your private key to the agent and enter your passphrase:

   ssh-add $env:USERPROFILE\.ssh\id_ed25519

Upload the public key to STACKIT

Only upload the public key. It’s stored in the file ending with .pub. Never upload or share your private key.

Prerequisites

• You have generated an SSH key pair.
• For the CLI: You have installed and authenticated the STACKIT CLI.
• For the API: You have a valid STACKIT access token and set it in the STACKIT_ACCESS_TOKEN environment variable. With the STACKIT CLI, you get a short-lived token for your user account, for example export STACKIT_ACCESS_TOKEN=$(stackit auth get-access-token) (Linux and macOS) or $env:STACKIT_ACCESS_TOKEN = stackit auth get-access-token (PowerShell).

Procedure

STACKIT Portal

1. Copy your public key to the clipboard:

   • macOS: pbcopy < ~/.ssh/id_ed25519.pub
   • Linux: xclip -selection clipboard < ~/.ssh/id_ed25519.pub (or wl-copy < ~/.ssh/id_ed25519.pub on Wayland)
   • Windows (PowerShell): Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

   Alternatively, display the key with cat (or Get-Content on Windows) and copy the complete line manually.

2. Open the SSH key settings in the STACKIT Portal.

3. Select + Create SSH key.

4. In the field Key name, enter a name that helps you identify the key, for example laptop-work.

5. In the field Please enter a key, paste your public key. Make sure you paste the complete line, starting with the key type, for example ssh-ed25519.

6. Select Create.

STACKIT CLI

Upload your public key directly from the file. The @ prefix tells the CLI to read the value from the file:

stackit key-pair create --name laptop-work --public-key @$HOME/.ssh/id_ed25519.pub

You can also add labels to the key:

stackit key-pair create --name laptop-work --public-key @$HOME/.ssh/id_ed25519.pub --labels team=ops

The CLI doesn’t expand ~, so use $HOME in the path. On Windows (PowerShell), use @$env:USERPROFILE\.ssh\id_ed25519.pub.

For all options, see the CLI reference for stackit key-pair.

STACKIT API

Send a POST request to the keypairs endpoint of the IaaS API:

curl -X POST "https://iaas.api.stackit.cloud/v2/keypairs" \
  -H "Authorization: Bearer $STACKIT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "laptop-work",
        "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q your_email@example.com"
      }'

For details, see the API reference for Keypairs.

After the upload, the key is shown in your list of SSH keys. STACKIT automatically calculates the fingerprint of the key. You can now select the key as initial credential when you create a VM.

List SSH keys

STACKIT Portal

1. Open the SSH key settings in the STACKIT Portal.

The page lists all SSH keys of the user you’re currently logged in with. For each key, the name, the fingerprint and the creation date are displayed.

STACKIT CLI

stackit key-pair list

STACKIT API

curl "https://iaas.api.stackit.cloud/v2/keypairs" \
  -H "Authorization: Bearer $STACKIT_ACCESS_TOKEN"

To check which local key belongs to a stored key, compare the fingerprint shown in the portal or the CLI with the MD5 fingerprint of your local key. STACKIT displays MD5 fingerprints, while ssh-keygen uses SHA256 by default, so add -E md5:

ssh-keygen -E md5 -lf ~/.ssh/id_ed25519.pub

Manage SSH keys

1. Open the SSH key settings in the STACKIT Portal.
2. Select the context menu of the SSH key you want to change by clicking on the three dots at the end of the row.
3. Select the action you want to perform. You can perform the actions Delete, Rename, and Set as Default.

Set as default

This action sets your selected SSH key as the default key. When you create a VM, this key is pre-selected as the initial credential. You can still choose a different SSH key during the VM creation process.

Rename

You can rename an SSH key. This action doesn’t change the key itself. Each key must have a unique name.

Delete

This action deletes an SSH key from your user account. After deletion, you can’t select this key when you create VMs. Existing VMs where the key was already added as initial credential aren’t affected. To revoke access to an existing VM, remove the key from the ~/.ssh/authorized_keys file of the user you use to connect to the VM.

You can also delete a key with the CLI (stackit key-pair delete <name>) or the API (DELETE https://iaas.api.stackit.cloud/v2/keypairs/<name>).

Next steps

• To connect to a VM, use ssh -i ~/.ssh/id_ed25519 <username>@<ip-address>. The username depends on the operating system image of the VM, see Username for SSH access.