Skip to main content
SSH keys are the recommended way to authenticate with Luumen. They’re more secure than passwords, don’t require typing a password on every connection, and can be revoked without changing access for other users. Luumen does not generate SSH keys for you. You generate keys on your own machine and import the private key into Luumen, where it’s encrypted and stored in Luumen’s cloud infrastructure.

​
Supported SSH key types

Luumen supports the following SSH key types:
  • Ed25519 (recommended)
  • RSA
  • ECDSA
All key types support optional passphrases. If your key has a passphrase, you’ll be prompted to enter it when importing the key into Luumen.

​
Generate a new SSH key

If you don’t already have an SSH key, generate one on your local machine using ssh-keygen. Ed25519 is recommended for new keys.

​
On macOS and Linux

Open a terminal and run:
Follow the prompts:
  • File location — accept the default (~/.ssh/id_ed25519) or choose a different path.
  • Passphrase — optional but recommended. The passphrase encrypts your private key on disk.
This creates two files:
  • id_ed25519 — your private key. Keep this safe and never share it.
  • id_ed25519.pub — your public key. This is the file you place on the servers you want to connect to.

​
On Windows

On Windows 10 (1809) or later, ssh-keygen is available in PowerShell or Command Prompt. Run the same command shown above. The keys are saved to C:\Users\<your-username>\.ssh\ by default.

​
Add your public key to a host

Before Luumen can connect using your key, the host must have your public key in its ~/.ssh/authorized_keys file. The exact steps depend on how you provision your servers — common methods include ssh-copy-id, configuration management tools like Ansible, or cloud provider key-injection at instance launch.

​
Import your private key into Luumen

In Luumen, SSH keys are stored as Credentials with Private Key authentication.
1

Open the Credentials widget

Open the Credentials widget from the hamburger menu.
2

Add a credential

Click Add credential and fill in the fields:
  • Name — a label for this credential, for example prod-ed25519-key.
  • Scope — choose Personal for individual access, or Workspace to share with your team (Team and Enterprise plans).
  • Username — the user account on the host you’ll be connecting to, for example ubuntu or admin.
  • Authentication — choose Private Key.
3

Add the key

Paste your private key into the key field, or upload the key file from your computer. If your key has a passphrase, enter it when prompted.
4

Save

Click Save. Your key is now stored securely in Luumen and can be assigned to any host that recognizes the matching public key.

​
Test your SSH key

After importing, verify the key works before relying on it:
  1. In the Credentials widget, click your new credential.
  2. Click Test.
Luumen attempts to authenticate to a host using the credential and reports whether the test succeeded. If the test fails, the most common causes are:
  • The matching public key isn’t in authorized_keys on the target host.
  • The username on the credential doesn’t match a user account on the host.
  • The private key has a passphrase and the wrong one was entered.
  • File permissions on ~/.ssh/authorized_keys are too open on the host (must be 600).

​
Rotate an SSH key

To rotate a key:
  1. Generate a new key on your local machine using ssh-keygen.
  2. Add the new public key to your hosts’ authorized_keys files.
  3. In Luumen, edit the existing credential and replace the private key, or add a new credential and reassign your hosts to it.
  4. Once you’ve confirmed the new key works, remove the old public key from your hosts and delete the old credential in Luumen.
Rotating keys regularly limits the impact of a compromised key and is a good practice for shared service accounts.

​
Next steps