Skip to main content

​
Overview

SSH key endpoints allow you to generate, import, and manage SSH keys for connecting to remote Borg repositories. Borg UI uses a single system SSH key for all connections.

​
Get System SSH Key

Get the system SSH key (there can be only one). Endpoint: GET /api/ssh-keys/system-key Example Request: 
curl http://localhost:5000/api/ssh-keys/system-key \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "success": true,
  "exists": true,
  "ssh_key": {
    "id": 1,
    "name": "System SSH Key",
    "description": "System SSH key for all remote connections",
    "key_type": "ed25519",
    "public_key": "ssh-ed25519 AAAAC3Nz... user@host",
    "fingerprint": "SHA256:abc123def456...",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "connection_count": 3,
    "active_connections": 2
  }
}
​
exists
boolean
Whether a system SSH key has been created
​
ssh_key.key_type
string
SSH key algorithm: rsa, ed25519, or ecdsa
​
ssh_key.fingerprint
string
SHA256 fingerprint of the public key
​
ssh_key.connection_count
integer
Total number of SSH connections configured
​
ssh_key.active_connections
integer
Number of connections with status “connected”

​
Generate System SSH Key

Generate a new system SSH key (one-time only). Endpoint: POST /api/ssh-keys/generate Admin Only: Yes
​
name
string
required
Name for the SSH key
​
key_type
string
default:"rsa"
Key algorithm: rsa, ed25519, or ecdsa
​
description
string
Optional description
Example Request: 
curl -X POST http://localhost:5000/api/ssh-keys/generate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "System SSH Key",
    "key_type": "ed25519",
    "description": "System key for remote repositories"
  }'
Response: 
{
  "success": true,
  "message": "System SSH key generated successfully",
  "ssh_key": {
    "id": 1,
    "name": "System SSH Key",
    "description": "System key for remote repositories",
    "key_type": "ed25519",
    "public_key": "ssh-ed25519 AAAAC3Nz... borg@borgui",
    "fingerprint": "SHA256:abc123def456...",
    "is_system_key": true,
    "is_active": true
  }
}

​
Import System SSH Key

Import an existing SSH key from the filesystem. Endpoint: POST /api/ssh-keys/import Admin Only: Yes
​
name
string
required
Name for the SSH key
​
private_key_path
string
required
Path to private key file (e.g., /local/.ssh/id_ed25519)
​
public_key_path
string
Path to public key file. If not provided, will try {private_key_path}.pub
​
description
string
Optional description
Example Request: 
curl -X POST http://localhost:5000/api/ssh-keys/import \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Imported Key",
    "private_key_path": "/local/.ssh/id_ed25519",
    "description": "Existing SSH key"
  }'

​
Delete SSH Key

Delete the system SSH key. Endpoint: DELETE /api/ssh-keys/{key_id} Admin Only: Yes Example Request: 
curl -X DELETE http://localhost:5000/api/ssh-keys/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
SSH Connections

​
List Connections

Get all SSH connections with storage information. Endpoint: GET /api/ssh-keys/connections Example Request: 
curl http://localhost:5000/api/ssh-keys/connections \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "success": true,
  "connections": [
    {
      "id": 1,
      "ssh_key_id": 1,
      "ssh_key_name": "System SSH Key",
      "host": "backup.example.com",
      "username": "borg",
      "port": 22,
      "use_sftp_mode": true,
      "default_path": "/backups",
      "ssh_path_prefix": null,
      "mount_point": "/remote-backups",
      "status": "connected",
      "last_test": "2024-01-15T10:00:00Z",
      "last_success": "2024-01-15T10:00:00Z",
      "error_message": null,
      "storage": {
        "total": 1099511627776,
        "total_formatted": "1.00 TB",
        "used": 549755813888,
        "used_formatted": "512.00 GB",
        "available": 549755813888,
        "available_formatted": "512.00 GB",
        "percent_used": 50.0,
        "last_check": "2024-01-15T10:00:00Z"
      },
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

​
Update Connection

Update SSH connection settings. Endpoint: PUT /api/ssh-keys/connections/{connection_id}
​
host
string
SSH host
​
username
string
SSH username
​
port
integer
SSH port
​
default_path
string
Default starting path for SSH browsing
​
ssh_path_prefix
string
Path prefix for SSH commands (e.g., /volume1 for Synology). SFTP uses path as-is, SSH prepends this prefix.
​
mount_point
string
Logical mount point (e.g., /hetzner)
​
use_sftp_mode
boolean
Use SFTP mode for ssh-copy-id (required by Hetzner, disable for Synology/older systems)
Example Request: 
curl -X PUT http://localhost:5000/api/ssh-keys/connections/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_path": "/new/path",
    "mount_point": "/remote"
  }'

​
Test Connection

Test an existing SSH connection. Endpoint: POST /api/ssh-keys/connections/{connection_id}/test Example Request: 
curl -X POST http://localhost:5000/api/ssh-keys/connections/1/test \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "success": true,
  "message": "Connection tested successfully",
  "status": "connected",
  "error": null
}

​
Refresh Storage Info

Refresh storage information for a connection. Endpoint: POST /api/ssh-keys/connections/{connection_id}/refresh-storage Example Request: 
curl -X POST http://localhost:5000/api/ssh-keys/connections/1/refresh-storage \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "success": true,
  "message": "Storage information refreshed successfully",
  "storage": {
    "total": 1099511627776,
    "total_formatted": "1.00 TB",
    "used": 549755813888,
    "used_formatted": "512.00 GB",
    "available": 549755813888,
    "available_formatted": "512.00 GB",
    "percent_used": 50.0,
    "last_check": "2024-01-15T10:05:00Z"
  }
}

​
Redeploy SSH Key

Redeploy the system SSH key to an existing connection. Endpoint: POST /api/ssh-keys/connections/{connection_id}/redeploy
​
password
string
required
SSH password for authentication
Example Request: 
curl -X POST http://localhost:5000/api/ssh-keys/connections/1/redeploy \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "ssh_password"
  }'

​
Delete Connection

Delete an SSH connection. Endpoint: DELETE /api/ssh-keys/connections/{connection_id} Example Request: 
curl -X DELETE http://localhost:5000/api/ssh-keys/connections/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Quick SSH Setup

Generate SSH key and deploy to remote server in one step. Endpoint: POST /api/ssh-keys/quick-setup Admin Only: Yes
​
name
string
required
Name for the SSH key
​
key_type
string
default:"rsa"
Key algorithm: rsa, ed25519, or ecdsa
​
host
string
Remote host for deployment
​
username
string
SSH username
​
port
integer
default:22
SSH port
​
password
string
SSH password for initial deployment
​
skip_deployment
boolean
default:false
Generate key only, skip deployment
​
use_sftp_mode
boolean
default:true
Use SFTP mode for ssh-copy-id (required by Hetzner, disable for Synology)
Example Request: 
curl -X POST http://localhost:5000/api/ssh-keys/quick-setup \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backup Server Key",
    "key_type": "ed25519",
    "host": "backup.example.com",
    "username": "borg",
    "port": 22,
    "password": "initial_password",
    "use_sftp_mode": true
  }'
Response: 
{
  "success": true,
  "message": "SSH key generated and deployed successfully",
  "ssh_key": {
    "id": 1,
    "name": "Backup Server Key",
    "key_type": "ed25519",
    "public_key": "ssh-ed25519 AAAAC3Nz... borg@borgui"
  },
  "connection": {
    "host": "backup.example.com",
    "username": "borg",
    "port": 22,
    "status": "connected"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us