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"
}

---

Modify User

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

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "userID": 1,
  "username": "user123",
  "passwd": "NewPass123!"
}

Response:

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

---

Modify User Type

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

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "userID": 2,
  "newType": "superadmin"
}

Response:

{
  "success": true,
  "message": "User type updated 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:

{
  "instanceID": "1"
}

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)

Response:

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

Field	Type	Description
instanceID	int	Instance ID
name	string	Name of the deleted frpc instance

---

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:

{
  "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
instanceID	string	Yes	Instance ID (the ID of the frpc instance)
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": {
    "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:

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

Field	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)
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": {
    "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

---

Start frpc Instance

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

Start a frpc instance. The instance can be started as a background process on Windows (hidden window) or as a systemd/init.d service on Linux.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1"
}

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	ID of the instance to start

Response (Windows):

{
  "success": true,
  "message": "Instance started successfully",
  "data": {}
}

Response (Linux systemd):

{
  "success": true,
  "message": "Instance started successfully",
  "data": {}
}

Response (Linux init.d):

{
  "success": true,
  "message": "Instance started successfully",
  "data": {}
}

---

Stop frpc Instance

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

Stop a running frpc instance. On Windows, this stops the frpc process. On Linux, this stops the systemd/init.d service.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1"
}

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	ID of the instance to stop

Response (Windows):

{
  "success": true,
  "message": "Instance stopped successfully",
  "data": {}
}

Response (Linux systemd):

{
  "success": true,
  "message": "Instance stopped successfully",
  "data": {}
}

Response (Linux init.d):

{
  "success": true,
  "message": "Instance stopped successfully",
  "data": {}
}

---

Restart frpc Instance

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

Restart a frpc instance. This stops and then starts the instance again.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1"
}

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	ID of the instance to restart

Response (Windows):

{
  "success": true,
  "message": "Instance restarted successfully",
  "data": {}
}

Response (Linux systemd):

{
  "success": true,
  "message": "Instance restarted successfully",
  "data": {}
}

Response (Linux init.d):

{
  "success": true,
  "message": "Instance restarted successfully",
  "data": {}
}

---

Get frpc Instance Status

Endpoint: /frpcAct/instanceMgr/status
Method: GET
Auth Required: Yes (token)
Permission Level: Visitor

Check the running status of a frpc instance.

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	ID of the instance to check

Response (running):

{
  "success": true,
  "message": "Instance status retrieved successfully",
  "data": {
    "name": "my_frpc",
    "initSystem": "systemd",
    "serviceName": "superfrpc_admin_my_frpc",
    "isRunning": true
  }
}

Response (stopped):

{
  "success": true,
  "message": "Instance status retrieved successfully",
  "data": {
    "name": "my_frpc",
    "initSystem": "systemd",
    "serviceName": "superfrpc_admin_my_frpc",
    "isRunning": false
  }
}

Field	Type	Description
name	string	Name of the frpc instance
initSystem	string	Operating system init system: "windows", "systemd", or "init.d"
serviceName	string	Service name (Linux only)
isRunning	boolean	Instance running status: true (running) or false (stopped)

---

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": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_my_frpc.toml",
    "proxyName": "ssh_proxy"
  }
}

Field	Type	Description
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

---

Modify Proxy

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

Modify an existing proxy configuration for an frpc instance. The proxy configuration will be updated in 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": "6001"
  }
}

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 (used to identify which proxy to modify)
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 modified successfully",
  "data": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_my_frpc.toml",
    "proxyName": "ssh_proxy"
  }
}

Field	Type	Description
instanceID	int	Instance ID
configPath	string	Path to the configuration file
proxyName	string	Name of the modified proxy

Config File Format:

The proxy configuration in the config file will be updated to the following format:

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

Note:

• The proxy configuration is updated in the existing config file
• The instance must already exist before modifying 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
• The proxy name is used to identify which proxy to modify; if the proxy is not found, an error will be returned

---

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": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_my_frpc.toml",
    "proxyName": "ssh_proxy"
  }
}

Field	Type	Description
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,
    "proxyCount": 2,
    "proxies": [
      {
        "name": "ssh_proxy",
        "type": "tcp",
        "localIP": "127.0.0.1",
        "localPort": "22",
        "remotePort": "6000"
      },
      {
        "name": "web_proxy",
        "type": "http",
        "localIP": "127.0.0.1",
        "localPort": "8080",
        "remotePort": "80"
      }
    ]
  }
}

Field	Type	Description
instanceID	int	Instance ID
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)
localIP	string	Local IP address to forward to
localPort	string	Local port to forward from
remotePort	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:

{
  "success": true,
  "message": "instances retrieved successfully",
  "data": [
    {
      "instanceID": 1,
      "name": "my_frpc",
      "createdAt": "2024-01-01T00:00:00Z",
      "createdBy": "admin",
      "isRunning": true
    }
  ]
}

Field	Type	Description
instanceID	int	Instance ID
name	string	Instance name
createdAt	string	Instance creation time (ISO 8601 format)
createdBy	string	Username of the user who created this instance
isRunning	bool	Instance running status: true (running) or false (stopped)

---

Get frpc Instance Information

Endpoint: /frpcAct/instanceMgr/getInfo
Method: GET
Auth Required: Yes (token)
Permission Level: Visitor

Retrieve information about a specific frpc instance. Returns different information based on user permission level.

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	ID of the instance to get information for

Response (Admin/Superuser):

{
  "success": true,
  "message": "Instance info retrieved successfully",
  "data": {
    "name": "my_frpc",
    "serviceName": "superfrpc_admin_my_frpc",
    "createdAt": "2024-01-01T00:00:00Z",
    "createdBy": "admin",
    "isRunning": true,
    "serverAddr": "127.0.0.1",
    "serverPort": "7000",
    "auth_method": "token",
    "bootAtStart": true,
    "runUser": "root",
    "configPath": "./configs/superfrpc_admin_my_frpc.toml"
  }
}

Response (Visitor):

{
  "success": true,
  "message": "Instance info retrieved successfully",
  "data": {
    "name": "my_frpc",
    "serviceName": "superfrpc_admin_my_frpc",
    "createdAt": "2024-01-01T00:00:00Z",
    "createdBy": "admin",
    "isRunning": true,
    "auth_method": "token",
    "bootAtStart": true,
    "runUser": "root",
    "configPath": "./configs/superfrpc_admin_my_frpc.toml"
  }
}

Field	Type	Description
name	string	Name of the frpc instance
serviceName	string	Service name
createdAt	string	Instance creation time (ISO 8601 format)
createdBy	string	Username of the user who created this instance
isRunning	bool	Instance running status: true (running) or false (stopped)
serverAddr	string	frps server address (only returned for admin/superuser)
serverPort	string	frps server port (only returned for admin/superuser)
auth_method	string	Authentication method
bootAtStart	bool	Whether the instance starts automatically on system boot
runUser	string	User that the instance runs as
configPath	string	Path to the instance's configuration file

---

Real-time System 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);
};

---

Real-time frpc Instance Log Streaming (WebSocket)

Endpoint: /frpcAct/instanceMgr/logs
Method: GET
Protocol: WebSocket
Auth Required: Yes (token)
Permission Level: Visitor

Stream real-time logs from a frpc instance via WebSocket connection. This endpoint upgrades the HTTP connection to WebSocket and streams log messages in real-time.

Request:

ws://host:port/frpcAct/instanceMgr/logs?instanceID=1&token=your_token

Query Parameters:

Parameter	Type	Required	Description
instanceID	int	Yes	ID of the instance to stream logs from
token	string	Yes	Authentication token

WebSocket Message Format:

Log messages are sent as JSON objects:

{
  "level": "INFO",
  "content": "[I] [service.go:XXX] start frpc success",
  "timestamp": "2024-01-01 12:00:00.000"
}

Field	Type	Description
level	string	Log level: "DEBUG", "INFO", "WARN", "ERROR"
content	string	Log message content
timestamp	string	Timestamp in "YYYY-MM-DD HH:MM:SS.mmm" format

Error Response (before WebSocket upgrade):

{
  "success": false,
  "message": "Instance not found"
}

Common Error Messages:

HTTP Status	Message	Description
400	"instanceID is required"	Missing instanceID parameter
400	"invalid instanceID format"	instanceID is not a valid integer
401	"Token is required"	Missing token parameter
401	"Invalid token: ..."	Token validation failed
401	"User not found"	User associated with token does not exist
403	"You don't have access to this instance"	Instance belongs to another user
404	"Instance not found"	Instance with given ID does not exist
500	"Failed to get service name"	Internal server error

Platform-Specific Behavior:

Platform	Init System	Log Source
Windows	sc	Config file (if log_file is set) or Windows Event Log
Linux	systemd	journalctl -u <service> -f
Linux	init.d	Log files in /var/log/ or service status monitoring

Connection Lifecycle:

1. Client initiates WebSocket connection with instanceID and token
2. Server validates token and instance ownership
3. Server upgrades connection to WebSocket
4. Server starts streaming logs
5. Connection remains open until client disconnects or error occurs
6. Server sends log messages as they become available

Notes:

• Only the instance owner can access the logs (user must own the instance)
• The connection will be closed if the token expires during the session
• On Windows, if no log file is configured, the service status is monitored instead
• On Linux init.d systems, log files are searched in common locations (/var/log/, etc.)
• Log streaming is real-time; historical logs may be sent initially depending on the platform

---

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.