Overview
The Machines API allows you to create, read, and delete SSH machine configurations. All endpoints require JWT authentication.
Create Machine
curl -X POST "http://localhost:8080/api/v1/machine" \
-H "Content-Type: application/json" \
-b "jwt=your-jwt-token" \
-d '{
"name": "Production Server",
"hostname": "192.168.1.100",
"port": "22",
"username": "ubuntu",
"password": "optional-password",
"private_key": "optional-private-key",
"passphrase": "optional-passphrase",
"organization": "my-org"
}'
POST /api/v1/machine
Create a new SSH machine configuration.
Request Body
Friendly name for the machine
IP address or hostname of the SSH server
SSH port (typically “22”)
SSH username for authentication
SSH password (required if not using private key). Encrypted before storage.
SSH private key (required if not using password). Encrypted before storage.
Passphrase for encrypted private key (optional). Encrypted before storage.
Organization identifier (optional)
Response
{
"status": "OK",
"message": "Machine created successfully",
"data": null
}
Error Responses
{
"status": "Unauthorized",
"message": "Invalid or missing JWT token",
"data": null
}
Show 500 - Database Error
{
"status": "Internal Server Error",
"message": "Error saving machine to database",
"data": null
}
List Machines
curl -X GET "http://localhost:8080/api/v1/machines" \
-b "jwt=your-jwt-token"
GET /api/v1/machines
Retrieve all machines for the authenticated user.
Response
{
"status": "OK",
"message": "Machines fetched successfully",
"data": [
{
"id": 1,
"name": "Production Server",
"username": "ubuntu",
"hostname": "192.168.1.100",
"port": "22",
"owner_id": "[email protected]",
"owner_type": "user"
},
{
"id": 2,
"name": "Development Server",
"username": "admin",
"hostname": "dev.example.com",
"port": "2222",
"owner_id": "[email protected]",
"owner_type": "user"
}
]
}
Response Fields
Unique machine identifier
SSH hostname or IP address
User email who owns this machine
Owner type (always “user”)
Notes
- Sensitive fields (password, private_key, passphrase) are NOT returned by this endpoint
- Only machines owned by the authenticated user are returned
- Results are filtered by username extracted from JWT token
Error Responses
{
"status": "Unauthorized",
"message": "Invalid or missing JWT token",
"data": null
}
Show 500 - Database Error
{
"status": "Internal Server Error",
"message": "Error fetching machines from database",
"data": null
}
Get Machine
curl -X GET "http://localhost:8080/api/v1/machine/1" \
-b "jwt=your-jwt-token"
GET /api/v1/machine/{id}
Retrieve details for a specific machine.
Path Parameters
Response
{
"status": "OK",
"message": "Machine fetched successfully",
"data": {
"id": 1,
"name": "Production Server",
"username": "ubuntu",
"hostname": "192.168.1.100",
"port": "22",
"owner_id": "[email protected]",
"owner_type": "user"
}
}
Response Fields
Unique machine identifier
SSH hostname or IP address
User email who owns this machine
Owner type (always “user”)
Notes
- Sensitive fields (password, private_key, passphrase) are NOT returned
- Users can only access machines they own
- Authorization is enforced via JWT username
Error Responses
{
"status": "Unauthorized",
"message": "Invalid or missing JWT token",
"data": null
}
{
"status": "Not Found",
"message": "Machine not found in database",
"data": null
}
Show 500 - Database Error
{
"status": "Internal Server Error",
"message": "Error fetching machine from database",
"data": null
}
Delete Machine
curl -X DELETE "http://localhost:8080/api/v1/machine/1" \
-b "jwt=your-jwt-token"
DELETE /api/v1/machine/{id}
Delete a machine configuration.
Path Parameters
Response
{
"status": "OK",
"message": "Machine deleted successfully",
"data": null
}
Notes
- Users can only delete machines they own
- Authorization is enforced via JWT username
- Deletion is permanent and cannot be undone
Error Responses
{
"status": "Unauthorized",
"message": "Invalid or missing JWT token",
"data": null
}
Show 500 - Database Error
{
"status": "Internal Server Error",
"message": "Error deleting machine from database",
"data": null
}
Connect to Machine
curl -X POST "http://localhost:8080/api/v1/machine/1/connect" \
-H "Content-Type: application/json" \
-b "jwt=your-jwt-token" \
-d '{
"password": "your-master-password"
}'
POST /api/v1/machine/{id}/connect
Initiate an SSH connection and retrieve a UUID for WebSocket connection.
Path Parameters
Request Body
Master password to decrypt machine credentials (encrypted private key, passphrase, or SSH password)
Response
{
"status": "OK",
"message": "Connected to machine successfully",
"data": "550e8400-e29b-41d4-a716-446655440000"
}
UUID for establishing WebSocket connection. Valid for the current time bucket (rounded to nearest minute).
Connection Flow
- User provides master password to decrypt credentials
- Machine credentials are retrieved from database and decrypted
- SSH connection is established to the remote machine
- UUID is generated and SSH client is stored in memory
- UUID is associated with a time bucket (rounded to nearest minute)
- Client uses UUID to establish WebSocket connection at
/ssh?uuid={uuid}
Notes
- The UUID is temporary and stored in memory with a time bucket
- Time buckets are used for automatic cleanup of stale connections
- The SSH connection remains open until WebSocket is established
- Users can only connect to machines they own
Error Responses
{
"status": "Unauthorized",
"message": "Invalid or missing JWT token",
"data": null
}
{
"status": "Not Found",
"message": "Machine not found in database",
"data": null
}
Show 500 - Connection Error
{
"status": "Internal Server Error",
"message": "Error connecting to machine",
"data": null
}
Show 500 - Database Error
{
"status": "Internal Server Error",
"message": "Error fetching machine from database",
"data": null
}
Show 500 - Decryption Error
{
"status": "Internal Server Error",
"message": "Error decoding post body",
"data": null
}