API Reference

The Web-Terminal REST API provides endpoints for terminal session management, authentication, and system operations. This API supports JWT authentication for terminal access control.

Table of contents

  1. API Reference
  2. Table of contents
  3. Interactive Documentation
    1. Direct Links
  4. Authentication Methods
    1. JWT Sessions (Web Interface)
  5. API Categories
    1. Terminal Session Management
    2. Authentication
    3. WebSocket Endpoints
  6. API Examples
    1. Terminal Session Management
      1. Start Terminal Session
      2. List Terminal Sessions
      3. Stop Terminal Session
    2. Authentication
      1. Basic Login
      2. Get Auth Methods
  7. Real-Time Features
    1. WebSocket Communication
  8. Response Formats
    1. Success Response
    2. Error Response
  9. Error Handling
  10. Rate Limiting
  11. Best Practices
    1. Security
    2. Performance
  12. Related Documentation

Interactive Documentation

Access the complete interactive Swagger UI at /api-docs on your Web-Terminal server

The Swagger UI provides:

  • Dark theme integration: Professional appearance matching Web-Terminal’s interface
  • API key management: Fill authentication directly from your existing keys
  • Temporary key generation: Create testing keys on-demand
  • Dynamic server detection: Auto-detects your server with custom override option
  • Live testing: Try all endpoints directly from the documentation

Authentication Methods

Web-Terminal supports JWT-based authentication:

JWT Sessions (Web Interface)

# Login to get JWT token
curl -k -X POST -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' \
  https://your-server/auth/login/basic

API Categories

Terminal Session Management

  • POST /api/terminal/start - Start a new terminal session
  • GET /api/terminal/sessions - List all terminal sessions
  • DELETE /api/terminal/sessions/{id}/stop - Stop a terminal session

Authentication

  • GET /auth/methods - Get available authentication methods
  • POST /auth/login/basic - Basic username/password login
  • POST /auth/logout - Logout and clear token
  • GET /auth/status - Check current authentication status

WebSocket Endpoints

  • WS /ws/terminal/{sessionId} - WebSocket connection for terminal I/O

API Examples

Terminal Session Management

Start Terminal Session

# Start a new terminal session
curl -k -X POST -H "Content-Type: application/json" \
  --cookie "auth_token=YOUR_JWT_TOKEN" \
  -d '{"terminal_cookie":"unique-session-id"}' \
  https://your-server/api/terminal/start

List Terminal Sessions

# Get all terminal sessions
curl -k --cookie "auth_token=YOUR_JWT_TOKEN" \
  https://your-server/api/terminal/sessions

Stop Terminal Session

# Stop a specific terminal session
curl -k -X DELETE --cookie "auth_token=YOUR_JWT_TOKEN" \
  https://your-server/api/terminal/sessions/SESSION_ID/stop

Authentication

Basic Login

# Authenticate with username/password
curl -k -X POST -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' \
  https://your-server/auth/login/basic

Get Auth Methods

# Check available authentication methods
curl -k https://your-server/auth/methods

Real-Time Features

WebSocket Communication

Web-Terminal uses WebSocket for real-time terminal I/O:

  • Bidirectional data streaming
  • Terminal resize events
  • Connection state tracking
  • Automatic reconnection

Response Formats

Success Response

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data varies by endpoint
  }
}

Error Response

{
  "success": false,
  "message": "Error description",
  "details": "Additional error information"
}

Error Handling

Web-Terminal uses standard HTTP status codes:

  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (authentication required)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found (session doesn’t exist)
  • 500 - Internal Server Error

Rate Limiting

API requests are subject to configurable rate limiting:

  • Default: 100 requests per 10-minute window
  • Headers include rate limit information:
    • RateLimit-Limit - Request limit
    • RateLimit-Remaining - Remaining requests
    • RateLimit-Reset - Reset time

Best Practices

Security

  • Use HTTPS for all API calls (-k flag with curl for self-signed certs)
  • Store JWT tokens securely
  • Implement proper session management
  • Monitor authentication attempts

Performance

  • Implement proper error handling for network timeouts
  • Monitor rate limit headers to avoid throttling
  • Use appropriate request timeouts
  • Handle WebSocket reconnection gracefully

Need help? Check our Support Documentation or open an issue.

Table of contents