SSH Keys - Pterodactyl Panel

Overview

SSH keys provide a secure method for authenticating to your servers via SFTP. Instead of using passwords, SSH keys use public-key cryptography to verify your identity.

Why Use SSH Keys?

More Secure: Cryptographic keys are much harder to crack than passwords
Convenient: No need to remember or type passwords for SFTP access
Required for Automation: Essential for automated deployment and backup scripts
Better Access Control: Each key can be individually managed and revoked

Supported Key Types

Pterodactyl supports the following SSH key types:

RSA

Minimum 2048 bits requiredRecommended: 4096 bits for maximum security

ECDSA

Fully SupportedModern elliptic curve algorithm

Ed25519

RecommendedFast, secure, and modern

DSA

Not SupportedDeprecated due to security concerns

RSA Key Requirements:

Minimum length: 2048 bits
Keys shorter than 2048 bits will be rejected
DSA keys are not supported due to security vulnerabilities

See StoreSSHKeyRequest.php:44-50 for validation logic.

Generating SSH Keys

If you don’t already have an SSH key, you can generate one using the ssh-keygen command.

Generate Ed25519 Key (Recommended)

ssh-keygen -t ed25519 -C "[email protected]"

Generate RSA Key (4096 bits)

ssh-keygen -t rsa -b 4096 -C "[email protected]"

Generation Process

Run the Command

Execute one of the ssh-keygen commands above in your terminal.

Choose Location

When prompted, press Enter to save the key in the default location (~/.ssh/id_ed25519 or ~/.ssh/id_rsa).Or specify a custom path:

Enter file in which to save the key: /home/user/.ssh/pterodactyl_key

Set Passphrase (Optional)

Enter a passphrase for additional security, or press Enter for no passphrase.

Using a passphrase adds an extra layer of security. Your SSH agent can remember it for the session.

Keys Generated

You’ll now have two files:

Private key: id_ed25519 (keep this secret!)
Public key: id_ed25519.pub (this is what you’ll upload)

Adding an SSH Key

Once you have an SSH key pair, add the public key to your Pterodactyl account.

Copy Your Public Key

Display and copy your public key:

cat ~/.ssh/id_ed25519.pub

The output will look like:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGQd... [email protected]

Copy the entire line.

Navigate to SSH Keys Settings

Go to Account Settings and select the SSH Keys section.

Click Add SSH Key

Click the Add SSH Key button.

Enter Key Details

Name: Give your key a descriptive name (e.g., “Work Laptop”, “Home Desktop”)
Public Key: Paste your entire public key

The system will automatically extract and validate the key format, converting it to PKCS8 format for storage (see StoreSSHKeyRequest.php:62-65).

Add Key

Click Add SSH Key to save it.

Verify

Your key will be added and you’ll see its fingerprint displayed. The fingerprint is a SHA256 hash of your public key.

SSH Key Validation

When you upload a public key, Pterodactyl performs several validation checks:

Format Validation

try {
    $this->key = PublicKeyLoader::loadPublicKey($this->input('public_key'));
} catch (NoKeyLoadedException $exception) {
    $this->validator->errors()->add('public_key', 'The public key provided is not valid.');
    return;
}

DSA Key Rejection

if ($this->key instanceof DSA) {
    $this->validator->errors()->add('public_key', 'DSA keys are not supported.');
}

RSA Length Requirement

if ($this->key instanceof RSA && $this->key->getLength() < 2048) {
    $this->validator->errors()->add('public_key', 'RSA keys must be at least 2048 bytes in length.');
}

Duplicate Detection

$fingerprint = $this->key->getFingerprint('sha256');
if ($this->user()->sshKeys()->where('fingerprint', $fingerprint)->exists()) {
    $this->validator->errors()->add('public_key', 'The public key provided already exists on your account.');
}

Understanding Fingerprints

Each SSH key has a unique fingerprint - a SHA256 hash that identifies the key. This is useful for:

Verifying you’re using the correct key
Identifying keys across different systems
Detecting duplicate keys

You can see your key’s fingerprint:

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

Output:

256 SHA256:AbCdEfGhIjKlMnOpQrStUvWxYz0123456789 [email protected] (ED25519)

Using SSH Keys for SFTP Access

Once you’ve added your SSH key, you can use it to connect via SFTP.

Command Line SFTP

sftp -P 2022 [email protected]

Replace:

2022 with your server’s SFTP port
username with your Pterodactyl username
abc123 with your server identifier
sftp.example.com with your panel’s SFTP address

FileZilla Configuration

Open Site Manager

In FileZilla, go to File → Site Manager

Add New Site

Click New Site and configure:

Protocol: SFTP - SSH File Transfer Protocol
Host: Your SFTP address
Port: Your SFTP port (usually 2022)
Logon Type: Key file
User: username.serverid
Key file: Browse to your private key file

Connect

Click Connect to establish the connection

WinSCP Configuration

Create a new session
Set File protocol to SFTP
Enter host and port
Enter username in format: username.serverid
Click Advanced → SSH → Authentication
Select your private key file
Click OK and Login

Managing SSH Keys

View Your SSH Keys

In the SSH Keys section, you can see:

Name: The descriptive name you provided
Fingerprint: The SHA256 fingerprint of the key
Created: When the key was added

The actual public key is stored in PKCS8 format in the database, but you’ll only see the fingerprint in the UI for security and brevity.

Delete an SSH Key

When you no longer use a device or want to revoke access:

Locate the Key

Find the SSH key you want to delete in your SSH Keys list.

Click Delete

Click the delete icon next to the key.

Confirm Deletion

Confirm that you want to delete the key.

Deleting an SSH key immediately revokes access. Any SFTP connections using this key will be disconnected and future connection attempts will fail.

Activity Logging

All SSH key operations are logged:

Key Added: user:ssh-key.create (includes fingerprint)
Key Deleted: user:ssh-key.delete (includes fingerprint)

You can review these events in your activity feed.

Security Best Practices

Use Strong Key Types

Prefer Ed25519 keys for the best combination of security and performance. If using RSA, use at least 4096 bits.

Protect Your Private Key

Never share your private key file
Set proper permissions: chmod 600 ~/.ssh/id_ed25519
Use a passphrase to encrypt the private key
Backup securely: Keep encrypted backups of your private key

Use Descriptive Names

Name your keys based on the device or purpose: “Work Laptop 2024”, “Home Desktop”, “CI/CD Pipeline”. This makes it easier to manage multiple keys.

One Key Per Device

Generate a separate key pair for each device. This allows you to revoke access from a single device without affecting others.

Regular Audits

Periodically review your SSH keys and remove any that are no longer needed or associated with devices you no longer use.

Rotate Keys Periodically

Generate new SSH keys periodically (e.g., annually) and remove old ones. This limits the impact of potential key compromise.

Troubleshooting

”The public key provided is not valid”

Ensure you’re copying the public key (.pub file), not the private key
Verify the key format is correct (should start with ssh-rsa, ssh-ed25519, or ecdsa-sha2-)
Make sure you copied the entire key, including the key type and email

”DSA keys are not supported”

DSA keys are deprecated due to security vulnerabilities. Generate a new Ed25519 or RSA key instead.

”RSA keys must be at least 2048 bytes in length”

Your RSA key is too short. Generate a new key with at least 2048 bits (4096 recommended):

ssh-keygen -t rsa -b 4096

“The public key provided already exists on your account”

This key has already been added to your account. Each key can only be added once. If you need to use the same key on multiple devices, you can - just don’t add it multiple times to Pterodactyl.

SFTP Connection Fails

Verify your SSH key has the file.sftp permission on the server
Check that you’re using the correct username format: username.serverid
Confirm the SFTP port and host are correct
Ensure your private key has proper permissions: chmod 600 ~/.ssh/id_ed25519
Check that your key wasn’t deleted or revoked

API Endpoint Reference

GET    /api/client/account/ssh-keys            # List all SSH keys
POST   /api/client/account/ssh-keys            # Add new SSH key
DELETE /api/client/account/ssh-keys            # Delete SSH key by fingerprint

For detailed API documentation, see the SSH Keys Reference.

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

​Overview

​Why Use SSH Keys?

​Supported Key Types

RSA

ECDSA

Ed25519

DSA

​Generating SSH Keys

​Generate Ed25519 Key (Recommended)

​Generate RSA Key (4096 bits)

​Generation Process

​Adding an SSH Key

​SSH Key Validation

​Format Validation

​DSA Key Rejection

​RSA Length Requirement

​Duplicate Detection

​Understanding Fingerprints

​Using SSH Keys for SFTP Access

​Command Line SFTP

​FileZilla Configuration

​WinSCP Configuration

​Managing SSH Keys

​View Your SSH Keys

​Delete an SSH Key

​Activity Logging

​Security Best Practices

​Troubleshooting

​”The public key provided is not valid”

​”DSA keys are not supported”

​”RSA keys must be at least 2048 bytes in length”

​“The public key provided already exists on your account”

​SFTP Connection Fails

​API Endpoint Reference

Build docs developers (and LLMs) love

Overview

Why Use SSH Keys?

Supported Key Types

Generating SSH Keys

Generate Ed25519 Key (Recommended)

Generate RSA Key (4096 bits)

Generation Process

Adding an SSH Key

SSH Key Validation

Format Validation

DSA Key Rejection

RSA Length Requirement

Duplicate Detection

Understanding Fingerprints

Using SSH Keys for SFTP Access

Command Line SFTP

FileZilla Configuration

WinSCP Configuration

Managing SSH Keys

View Your SSH Keys

Delete an SSH Key

Activity Logging

Security Best Practices

Troubleshooting

”The public key provided is not valid”

”DSA keys are not supported”

”RSA keys must be at least 2048 bytes in length”

“The public key provided already exists on your account”

SFTP Connection Fails

API Endpoint Reference