API Overview

Base URL

All API endpoints are prefixed with:

/api/v1

For a local deployment:

http://localhost:8080/api/v1

API Structure

The suSHi API is organized into the following sections:

Authentication - OAuth 2.0 endpoints for Google and GitHub login
Machines - CRUD operations for SSH machine management
SSH WebSocket - Real-time SSH terminal connections

Response Format

All API responses follow a consistent JSON structure:

{
  "status": "OK",
  "message": "Descriptive message",
  "data": {} // Optional response data
}

status

string

required

HTTP status text (e.g., “OK”, “Bad Request”, “Internal Server Error”)

message

string

required

Human-readable message describing the result

data

object

Response payload (structure varies by endpoint)

Authentication

Most endpoints require JWT authentication. After completing the OAuth flow, you’ll receive a JWT token in a cookie named jwt.

Protected Endpoints

All endpoints under /api/v1/* (except /api/v1/auth/*) require authentication via JWT token. The JWT token must be included as a cookie:

Cookie: jwt=<your-jwt-token>

Public Endpoints

The following endpoints do NOT require authentication:

GET /api/v1/auth/url - Get OAuth authorization URL
GET /api/v1/auth/callback - OAuth callback handler
GET /api/v1/auth/logout - Logout endpoint

Error Responses

Error responses use standard HTTP status codes:

Status Code	Description
400	Bad Request - Missing or invalid parameters
401	Unauthorized - Invalid or missing JWT token
404	Not Found - Resource not found
500	Internal Server Error - Server-side error

Example Error Response

{
  "status": "Bad Request",
  "message": "Missing query param 'to'",
  "data": null
}

Rate Limiting

Currently, the API does not implement rate limiting. This may change in future versions.

CORS

WebSocket connections accept all origins. REST API CORS settings depend on your deployment configuration.

Endpoints

​Base URL

​API Structure

​Response Format

​Authentication

​Protected Endpoints

​Public Endpoints

​Error Responses

​Example Error Response

​Rate Limiting

​CORS

Build docs developers (and LLMs) love