API Routes

May 24, 2026 · View on GitHub

← Back to API | ← Back to Documentation

Overview

WebSSH2 provides several HTTP routes for different authentication methods and utility functions.

Main Routes

URL: http(s)://your-webssh2-server/ssh
Method: GET
Features:
- Interactive login form
- Terminal configuration options
- Supports both password and private key authentication

Screenshots:

Terminal Configuration:

2. `/ssh/host/:host` - HTTP Basic Auth ⚠️ DEPRECATED

⚠️ DEPRECATION NOTICE: HTTP Basic Authentication is deprecated and may be removed in a future version. We strongly recommend using HTTP POST Authentication for SSO integration and modern authentication workflows.

URL: http(s)://your-webssh2-server/ssh/host/:host
Method: GET
Authentication: HTTP Basic Auth (deprecated)
Status: Still functional but deprecated
Features:
- Quick connections to specific hosts
- Optional port parameter (e.g., ?port=2222)
Migration: Use POST authentication for new implementations

HTTP Basic Auth Behavior

WebSSH2 validates SSH credentials immediately upon receiving HTTP Basic Auth credentials. This ensures only valid SSH credentials proceed to the terminal interface.

Expected Behavior:

URL without embedded credentials:
```
http://localhost:2222/ssh/host/example.com
```
- Invalid credentials → 401 Unauthorized
- Browser shows auth dialog
- User can enter correct credentials
- Success
URL with embedded credentials:
```
http://user:pass@localhost:2222/ssh/host/example.com
```
- Browser always uses URL credentials
- Never prompts for new ones
- Invalid credentials → 401 Unauthorized
- No re-authentication possible
- User must manually remove bad credentials from URL to retry

Important: This is standard HTTP Basic Auth behavior. URLs with embedded credentials take absolute precedence over HTTP auth dialogs. For interactive re-authentication on failure, use URLs without embedded credentials.

3. `/ssh` - HTTP POST Auth ✅ RECOMMENDED

URL: http(s)://your-webssh2-server/ssh
Method: POST
Content-Type: application/json
Status: Recommended for SSO and modern authentication
Features:
- Clean separation from Basic Auth routes
- Better integration with SSO systems (SAML, OAuth)
- More secure credential handling
- Compatible with CSRF protection
- Supports complex authentication flows
- Better suited for programmatic access
- No session credential conflicts

Request Body

{
  "username": "string",        // Required
  "password": "string",        // Required
  "host": "string",           // Required
  "port": 22,                 // Optional (default: 22)
  "sshterm": "xterm-256color" // Optional
}

Example: Basic POST Request

curl -X POST "http://localhost:2222/ssh" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "myuser",
    "password": "mypass",
    "host": "example.com",
    "port": 22,
    "sshterm": "xterm-256color"
  }'

Example: SSO Integration

// SAML/OAuth → WebSSH2 integration
const response = await fetch('/ssh', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${ssoToken}`
  },
  body: JSON.stringify({
    username: await getSSOUsername(ssoToken),
    password: await getSSOPassword(ssoToken),
    host: targetHost,
    port: 22
  })
});

Utility Routes

`/ssh/reauth` - Clear Session and Re-authenticate

URL: http(s)://your-webssh2-server/ssh/reauth
Method: GET
Purpose: Clears all stored session credentials and redirects to fresh login
Use Case: When credentials are stuck or you need to force re-authentication
Behavior: Clears session and redirects to /ssh
Response: 302 Redirect to /ssh

`/ssh/clear-credentials` - Clear Credentials Only

URL: http(s)://your-webssh2-server/ssh/clear-credentials
Method: GET
Purpose: Clears stored SSH credentials from session
Response: 200 OK with body: "Credentials cleared"

`/ssh/force-reconnect` - Force Re-authentication

URL: http(s)://your-webssh2-server/ssh/force-reconnect
Method: GET
Purpose: Clears credentials and returns 401 Unauthorized
Response: 401 Unauthorized with body: "Authentication required"

Query Parameters

All routes support the following query parameters:

Parameter	Type	Default	Description
`port`	integer	22	SSH port to connect to
`sshterm`	string	xterm-color	Terminal type
`header`	string	-	Header text override
`headerBackground`	string	green	Header background color
`env`	string	-	Comma-separated env pairs (e.g., `FOO:bar,BAR:baz`)

Example with Query Parameters

http://localhost:2222/ssh/host/example.com?port=2244&sshterm=xterm-256color&env=DEBUG:true,NODE_ENV:production

Response Codes

Code	Description
200	Success
302	Redirect (for reauth)
400	Bad Request (invalid parameters)
401	Unauthorized (authentication required or failed)
404	Not Found (invalid route)
500	Internal Server Error
502	Bad Gateway (SSH server unreachable)
504	Gateway Timeout (SSH connection timed out)

Error Response Format

WebSSH2 uses content negotiation to return appropriate error responses based on the client type.

Browser Requests (Accept: text/html)

When a browser requests a page and an SSH error occurs, WebSSH2 returns a styled HTML error page with:

Error title and description
Host and port details
"Try Again" button (for 401 authentication errors)

This provides a user-friendly experience instead of raw JSON.

API Requests (Accept: application/json)

API clients receive JSON error responses:

{
  "error": "Connection failed",
  "message": "Handshake failed: no matching key exchange algorithm",
  "host": "example.com",
  "port": 22
}

Content Negotiation

The response format is determined by the Accept header:

If text/html appears before application/json → HTML error page
Otherwise → JSON response

Examples:

# Browser request - gets HTML error page
curl -H "Accept: text/html" \
  "http://localhost:2222/ssh/host/example.com"

# API request - gets JSON response
curl -H "Accept: application/json" \
  -u "user:pass" \
  "http://localhost:2222/ssh/host/example.com"

Migration Guide

From Basic Auth to POST Auth

Old Method (Deprecated):

// Using Basic Auth
window.location.href = 'http://user:pass@server:2222/ssh/host/example.com';

New Method (Recommended):

// Using POST Auth
fetch('/ssh', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'user',
    password: 'pass',
    host: 'example.com',
    port: 22
  })
});

Security Considerations

Always use HTTPS in production to protect credentials in transit
POST authentication is more secure than Basic Auth
Avoid embedding credentials in URLs
Use SSO integration when possible for enterprise deployments
Configure CORS properly via http.origins configuration

Telnet Routes

Telnet support is disabled by default. Set WEBSSH2_TELNET_ENABLED=true or telnet.enabled: true in config.json to enable these routes. See Configuration for all telnet options.

Security Warning: Telnet transmits all data, including credentials, in plain text. Only use on trusted, isolated networks. Prefer SSH whenever possible.

URL: http(s)://your-webssh2-server/telnet
Method: GET
Features:
- Interactive login form (telnet-specific UI)
- Security warning banner displayed to users
- Expect-style authentication with configurable prompt patterns
- SFTP and host key features hidden (SSH-only)

2. `/telnet/host/:host` - Host-Locked Mode

URL: http(s)://your-webssh2-server/telnet/host/:host
Method: GET
Features:
- Direct connection to a specific telnet host
- Optional port parameter (e.g., ?port=2323, default: 23)
- Host is locked and cannot be changed by the user

3. `/telnet` - HTTP POST Auth

URL: http(s)://your-webssh2-server/telnet
Method: POST
Content-Type: application/json
Features:
- SSO form submission for telnet connections
- Same integration patterns as SSH POST auth

Request Body

{
  "username": "string",
  "password": "string",
  "host": "string",
  "port": 23
}

4. `/telnet/host/:host` - POST with Host Locked

URL: http(s)://your-webssh2-server/telnet/host/:host
Method: POST
Features:
- SSO form submission with host pre-set
- Host parameter locked from URL path

5. `/telnet/config` - Telnet Configuration Endpoint

URL: http(s)://your-webssh2-server/telnet/config
Method: GET
Purpose: Exposes telnet server configuration to clients
Response: JSON with protocol, defaultPort, and term

{
  "protocol": "telnet",
  "defaultPort": 23,
  "term": "vt100"
}

Telnet Query Parameters

Parameter	Type	Default	Description
`port`	integer	23	Telnet port to connect to
`header`	string	-	Header text override
`headerBackground`	string	green	Header background color

Telnet Examples

http://localhost:2222/telnet/host/192.168.1.1?port=2323

# Docker with telnet enabled
docker run --rm -p 2222:2222 \
  -e WEBSSH2_TELNET_ENABLED=true \
  ghcr.io/billchurch/webssh2:latest