backend/docs/api.md

API Documentation

All API responses are returned in JSON format:

Success Response:

{
  "success": true,
  "message": "success message",
  "data": { ... }
}

Error Response:

{
  "success": false,
  "message": "error message"
}

Important Notes:

• For all requests: Authentication token and timestamp are sent in HTTP headers (prefixed with X-)
• For POST requests: Other data is sent in the request body as JSON
• For GET requests: All data is sent in HTTP headers (prefixed with X-)
• All requests require authentication (except /register, /login, /system/getStatus, /system/getSoftwareInfo)
• Timestamps are in milliseconds (Unix timestamp)

---

Get System Status

Endpoint: /system/getStatus
Method: GET
Auth Required: No
Permission Level: None

Get the current system status.

Response:

{
  "success": true,
  "message": "getStatus",
  "data": {
    "Status": "Online"
  }
}

Field	Type	Description
Status	string	System status: "Online" or "Offline"

---

Get Software Info

Endpoint: /system/getSoftwareInfo
Method: GET
Auth Required: No
Permission Level: None

Get software version and build information.

Response:

{
  "success": true,
  "message": "getSoftwareInfo",
  "data": {
    "Name": "Super-frpc",
    "Version": "0.0.1",
    "Developer": "Madobi Nanami",
    "BuildVer": 1,
    "Description": "",
    "BuildType": "debug"
  }
}

Field	Type	Description
Name	string	Software name
Version	string	Software version
Developer	string	Developer name
BuildVer	int16	Build version number
Description	string	Software description
BuildType	string	Build type: "debug" or "release"

---

Register User

Endpoint: /register
Method: POST
Content-Type: application/json Permission Level: None

Request Headers:

X-Timestamp: 1704067200000

Request Body:

{
  "username": "your_username",
  "passwd": "YourPass123!"
}

Header	Type	Required	Description
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
username	string	Yes	Username (no special characters)
passwd	string	Yes	Password (must contain uppercase, lowercase, digit, and special character, min 8 chars)
type	string	No	User type: superuser, admin, visitor (default: visitor)

Response:

{
  "success": true,
  "message": "user registered successfully",
  "data": {
    "userID": 1,
    "username": "your_username",
    "type": "admin"
  }
}

New user only can register as visitor, superuser and admin need to contact the administrator to apply.

---

Login

Endpoint: /login
Method: POST
Content-Type: application/json
Permission Level: None

Request Headers:

X-Timestamp: 1704067200000

Request Body:

{
  "username": "your_username",
  "passwd": "YourPass123!"
}

Header	Type	Required	Description
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
username	string	Yes	Username
passwd	string	Yes	Password

Response:

{
  "success": true,
  "message": "login successful",
  "data": {
    "token": "xxxxxxxxxxxxx",
    "userID": 1,
    "username": "your_username",
    "type": "admin"
  }
}

---

Logout

Endpoint: /logout
Method: GET
Auth Required: Yes (token) Permission Level: None

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Response:

{
  "success": true,
  "message": "Logout successful"
}

---

Create User

Endpoint: /userMgr/create
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Superuser

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "username": "new_user",
  "passwd": "NewPass123!",
  "type": "admin"
}

Response:

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "userID": 2,
    "username": "new_user",
    "type": "admin"
  }
}

---

Remove User

Endpoint: /userMgr/remove
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Superuser

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "targetUserID": 2
}

Response:

{
  "success": true,
  "message": "User removed successfully"
}

---

List Users

Endpoint: /userMgr/list
Method: GET
Auth Required: Yes (token)
Permission Level: Superuser

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Response:

{
  "success": true,
  "message": "User list retrieved successfully",
  "data": [
    {
      "UserID": 1,
      "Username": "admin",
      "Passwd": "",
      "Type": "superuser",
      "CreatedAt": "2024-01-01 12:00:00"
    },
    {
      "UserID": 2,
      "Username": "new_user",
      "Passwd": "",
      "Type": "admin",
      "CreatedAt": "2024-01-02 14:30:00"
    }
  ]
}

Field	Type	Description
UserID	int	User ID
Username	string	Username
Type	string	User type: superuser, admin, visitor
CreatedAt	string	User creation time (YYYY-MM-DD HH:MM:SS format)

---

List Active Sessions

Endpoint: /sessionMgr/list
Method: GET
Auth Required: Yes (token)
Permission Level: Superuser, Admin

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Response:

{
  "success": true,
  "message": "Active sessions listed",
  "data": [
    {
      "ID": "session-5f4dcc3b5aa765d61d8327deb882cf99-1704067200000",
      "UserID": 1,
      "Username": "admin",
      "ExpireAt": "2024-01-01T01:00:00Z"
    },
    {
      "ID": "session-7c6a180b36896a0a8c010710c0780347-1704067210000",
      "UserID": 2,
      "Username": "new_user",
      "ExpireAt": "2024-01-01T01:00:10Z"
    }
  ]
}

Field	Type	Description
ID	string	Unique session ID
UserID	int	User ID
Username	string	Username
ExpireAt	string	Session expiration time (ISO 8601 format)

---

Remove Session

Endpoint: /sessionMgr/remove
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Superuser

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "sessionID": "session-5f4dcc3b5aa765d61d8327deb882cf99-1704067200000"
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
sessionID	string	Yes	Session ID to remove

Response:

{
  "success": true,
  "message": "Session removed successfully"
}

Note

: This endpoint requires superuser permission. It removes a session by its sessionID and also removes the associated token, forcing the user to re-login.

---

Create frpc Instance

Endpoint: /frpcAct/instanceMgr/create
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceInfo": {
    "name": "my_frpc",
    "serverAddr": "127.0.0.1",
    "serverPort": "7000",
    "auth_method": "token"
  },
  "bootAtStart": true,
  "runUser": "root",
  "additionalProperties": {
    "pool_count": 5
  }
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceInfo.name	string	Yes	Instance name
instanceInfo.serverAddr	string	Yes	frps server address
instanceInfo.serverPort	string	Yes	frps server port
instanceInfo.auth_method	string	Yes	Authentication method
bootAtStart	bool	No	Auto-start on system boot (default: false)
runUser	string	No	Run as user (default: root)
additionalProperties	object	No	Additional frpc configuration

Response:

{
  "success": true,
  "message": "instance created successfully",
  "data": {
    "name": "my_frpc",
    "configPath": "./configs/superfrpc_user_my_frpc.toml",
    "bootAtStart": true
  }
}

---

Delete frpc Instance

Endpoint: /frpcAct/instanceMgr/delete
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceName": "my_frpc"
}

Response:

{
  "success": true,
  "message": "instance deleted successfully",
  "data": {
    "name": "my_frpc"
  }
}

---

Modify frpc Instance

Endpoint: /frpcAct/instanceMgr/modify
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Modify instance configuration. Supports two modification types: configFile (modify frpc config file) and systemConfig (modify system-level settings).

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Type 1: Modify Config File (configFile)

Modify fields in the [common] section of the frpc configuration file. Only [common] section fields can be modified, [[proxies]] sections will not be affected.

Request Body:

{
  "instanceName": "my_frpc",
  "instanceID": "1",
  "type": "configFile",
  "modifiedData": {
    "server_addr": "192.168.1.1",
    "server_port": "7000",
    "auth_method": "token",
    "auth_token": "my_secret_token"
  }
}

Field	Type	Required	Description
instanceName	string	Yes	Current instance name
instanceID	string	Yes	Instance ID
type	string	Yes	Modification type: configFile or systemConfig
modifiedData	object	Yes	Key-value pairs of fields to modify in [common] section

Response:

{
  "success": true,
  "message": "Config file modified successfully",
  "data": {
    "instanceName": "my_frpc",
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_my_frpc.toml"
  }
}

Type 2: Modify System Config (systemConfig)

Modify system-level settings such as instance name, boot-at-start configuration, and run user. These changes will also update the operating system service configuration.

Request Body:

{
  "instanceName": "my_frpc",
  "instanceID": "1",
  "type": "systemConfig",
  "modifiedData": {
    "name": "new_frpc_name",
    "bootAtStart": true,
    "runUser": "www-data"
  }
}

Field	Type	Required	Description
instanceName	string	Yes	Current instance name
instanceID	string	Yes	Instance ID
type	string	Yes	Modification type: configFile or systemConfig
modifiedData.name	string	No	New instance name (renames config file if changed)
modifiedData.bootAtStart	bool	No	Auto-start on system boot
modifiedData.runUser	string	No	User to run the frpc instance as

Response:

{
  "success": true,
  "message": "System config modified successfully",
  "data": {
    "instanceName": "new_frpc_name",
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_new_frpc_name.toml",
    "bootAtStart": true,
    "runUser": "www-data"
  }
}

Response with bootServiceError (when boot service operations fail):

{
  "success": true,
  "message": "System config modified successfully",
  "data": {
    "instanceName": "new_frpc_name",
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_new_frpc_name.toml",
    "bootAtStart": true,
    "runUser": "www-data",
    "bootServiceError": "Failed to create boot service: unsupported init system"
  }
}

Note about bootServiceError:

• The bootServiceError field appears in the response when boot service operations (create/remove) fail
• This field is only present when there is an error; it will not be included in the response if operations succeed
• The overall request still returns success: true because the system config modification (database update, config file rename, etc.) succeeded
• Common scenarios where bootServiceError may appear:
  • Enabling bootAtStart when the init system is not supported (e.g., on Windows or systems without systemd/init.d)
  • Disabling bootAtStart when the service file cannot be removed due to permission issues
  • Changing instance name or run user when bootAtStart is enabled (requires removing old service and creating new one)
• The error message provides detailed information about what went wrong, which should be displayed to the user
• Frontend applications should check for this field and display the error message to the user, even though the request was technically successful

---

Create Proxy

Endpoint: /frpcAct/proxyMgr/create
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Create a new proxy configuration for an existing frpc instance. The proxy configuration will be appended to the instance's config file.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1",
  "proxyInfo": {
    "name": "ssh_proxy",
    "type": "tcp",
    "localIP": "127.0.0.1",
    "localPort": "22",
    "remotePort": "6000"
  }
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)
proxyInfo.name	string	Yes	Proxy name
proxyInfo.type	string	Yes	Proxy type (e.g., tcp, udp, http, https)
proxyInfo.localIP	string	Yes	Local IP address to forward to
proxyInfo.localPort	string	Yes	Local port to forward from
proxyInfo.remotePort	string	Yes	Remote port on frps to expose

Response:

{
  "success": true,
  "message": "Proxy created successfully",
  "data": {
    "instanceName": "my_frpc",
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_my_frpc.toml",
    "proxyName": "ssh_proxy"
  }
}

Field	Type	Description
instanceName	string	Name of the frpc instance
instanceID	int	Instance ID
configPath	string	Path to the configuration file
proxyName	string	Name of the created proxy

Config File Format:

The proxy configuration will be appended to the instance's config file in the following format:

[[proxies]]
name = ssh_proxy
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = 6000

Note:

• The proxy configuration is appended to the existing config file
• The instance must already exist before creating a proxy
• This endpoint does not modify the database, only the config file
• The frpc service needs to be restarted for changes to take effect

---

Delete Proxy

Endpoint: /frpcAct/proxyMgr/delete
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Delete an existing proxy configuration from an frpc instance. The proxy configuration will be removed from the instance's config file.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1",
  "proxyName": "ssh_proxy"
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)
proxyName	string	Yes	Name of the proxy to delete

Response:

{
  "success": true,
  "message": "Proxy deleted successfully",
  "data": {
    "instanceName": "my_frpc",
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_my_frpc.toml",
    "proxyName": "ssh_proxy"
  }
}

Field	Type	Description
instanceName	string	Name of the frpc instance
instanceID	int	Instance ID
configPath	string	Path to the configuration file
proxyName	string	Name of the deleted proxy

Note:

• The proxy configuration is removed from the existing config file
• The instance must already exist before deleting a proxy
• This endpoint does not modify the database, only the config file
• The frpc service needs to be restarted for changes to take effect

---

List Proxies

Endpoint: /frpcAct/proxyMgr/list
Method: GET
Auth Required: Yes (token)
Permission Level: None (any permission level)

Retrieve a list of all proxy configurations for a specific frpc instance. The proxy configurations are read from the instance's config file.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Query Parameters:

?instanceID=1

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Parameter	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)

Response:

{
  "success": true,
  "message": "Proxies listed successfully",
  "data": {
    "instanceID": 1,
    "instanceName": "my_frpc",
    "proxyCount": 2,
    "proxies": [
      {
        "name": "ssh_proxy",
        "type": "tcp",
        "local_ip": "127.0.0.1",
        "local_port": "22",
        "remote_port": "6000"
      },
      {
        "name": "web_proxy",
        "type": "http",
        "local_ip": "127.0.0.1",
        "local_port": "8080",
        "remote_port": "80"
      }
    ]
  }
}

Field	Type	Description
instanceID	int	Instance ID
instanceName	string	Name of the frpc instance
proxyCount	int	Number of proxies
proxies	array	List of proxy configurations

Proxy Object:

Field	Type	Description
name	string	Proxy name
type	string	Proxy type (e.g., tcp, udp, http, https)
local_ip	string	Local IP address to forward to
local_port	string	Local port to forward from
remote_port	string	Remote port on frps to expose

Note:

• The proxy configurations are read from the existing config file
• This endpoint does not modify the database, only reads the config file
• The returned proxy list represents the current configuration in the file
• Changes to the config file will be reflected in subsequent requests

---

List frpc Instances

Endpoint: /frpcAct/instanceMgr/list
Method: GET
Auth Required: Yes (token)
Permission Level: Admin

Retrieve a list of all frpc instances on the server.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Response (admin/superuser):

{
  "success": true,
  "message": "instances retrieved successfully",
  "data": [
    {
      "instanceID": 1,
      "name": "my_frpc",
      "serverAddr": "127.0.0.1",
      "serverPort": "7000",
      "auth_method": "token",
      "bootAtStart": true,
      "runUser": "root",
      "configPath": "./configs/superfrpc_user_my_frpc.toml",
      "createdAt": "2024-01-01T00:00:00Z",
      "createdBy": "admin"
    }
  ]
}

Response (visitor):

{
  "success": true,
  "message": "instances retrieved successfully",
  "data": [
    {
      "instanceID": 1,
      "name": "my_frpc",
      "bootAtStart": true,
      "runUser": "root",
      "configPath": "./configs/superfrpc_user_my_frpc.toml",
      "createdAt": "2024-01-01T00:00:00Z",
      "createdBy": "admin"
    }
  ]
}

Field	Type	Description
instanceID	int	Instance ID
name	string	Instance name
serverAddr	string	frps server address (admin/superuser only)
serverPort	string	frps server port (admin/superuser only)
auth_method	string	Authentication method (admin/superuser only)
bootAtStart	bool	Auto-start on system boot
runUser	string	User to run the frpc instance as
configPath	string	Path to the configuration file
createdAt	string	Instance creation time (ISO 8601 format)
createdBy	string	Username of the user who created this instance

Note: Visitor users do not see sensitive information (serverAddr, serverPort, auth_method).

---

Real-time Log Streaming (WebSocket)

Endpoint: /system/getLogs
Protocol: WebSocket
Auth Required: Yes (token)
Permission Level: None

Establish a WebSocket connection to receive real-time log streaming from the server.

Connection

Connect to ws://localhost:8080/system/getLogs (or wss:// for secure connection).

Query Parameters:

• token: Authentication token (optional, for tracking which user is viewing logs)

Example:

ws://localhost:8080/logs?token=your_token_here

Message Format

Logs are sent as JSON messages with the following structure:

{
  "level": 1,
  "content": "Log message content",
  "timestamp": "2024-01-01 12:00:00.000"
}

Field	Type	Description
level	int	Log level: 0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR, 4=FATAL
content	string	Log message content
timestamp	string	Log timestamp (YYYY-MM-DD HH:MM:SS.mmm format)

Log Levels

Level	Name	Description
0	DEBUG	Debug messages (only visible when debug mode is enabled)
1	INFO	Informational messages
2	WARNING	Warning messages
3	ERROR	Error messages
4	FATAL	Fatal/critical messages

Behavior

1. On Connection: The server immediately sends the last 100 log entries
2. Streaming: All new log entries are pushed in real-time to all connected clients
3. Multi-client: Multiple clients can connect simultaneously and receive the same log stream
4. History: Only the most recent 100 log entries are kept in memory

Example Usage (JavaScript)

const socket = new WebSocket('ws://localhost:8080/logs?token=your_token');

socket.onopen = () => {
  console.log('Connected to log server');
};

socket.onmessage = (event) => {
  const log = JSON.parse(event.data);
  console.log(`[${log.timestamp}] ${log.content}`);
  
  // Log level example
  const levels = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'FATAL'];
  console.log(`[${levels[log.level]}] ${log.content}`);
};

socket.onclose = () => {
  console.log('Disconnected from log server');
};

socket.onerror = (error) => {
  console.error('WebSocket error:', error);
};

---

User Permissions

Permission	superuser	admin	visitor
Create instance	✓	✓	✗
Delete instance	✓	✓	✗
Modify instance	✓	✓	✗
List instances	✓	✓	✓ (limited)
Manage users	✓	✗	✗
List active sessions	✓	✓	✗
View logs	✓	✓	✓

---

Timestamp Validation

All requests include a timeStamp field (Unix timestamp in milliseconds). The server validates that the timestamp is within ±3000ms of the server time. This prevents replay attacks.

---

Password Requirements

Passwords must meet the following complexity requirements:

• At least 8 characters
• At least one uppercase letter (A-Z)
• At least one lowercase letter (a-z)
• At least one digit (0-9)
• At least one special character (!@#$%^&*()_+-=[]{}|;:,.<>?)

---

Token

Tokens are valid for 1 hour. After expiration, users need to re-login to get a new token.

---

Generated Config Files

Instance configuration files are saved in the specified instancePath with the naming convention:

superfrpc_<username>_<instanceName>.toml

Example: superfrpc_admin_my_frpc.toml

---

Error Codes

Code	Message	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
500	Internal Server Error	Server internal error

---

Rate Limiting

The API implements rate limiting to prevent abuse:

• Login attempts: Maximum 5 attempts per minute per IP
• All other endpoints: 100 requests per minute per token

Exceeding rate limits will result in temporary IP or token blocking.