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 and /login)
• Timestamps are in milliseconds (Unix timestamp)

---

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",
      "type": "superuser"
    },
    {
      "userID": 2,
      "username": "new_user",
      "type": "admin"
    }
  ]
}

---

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

---

List frpc Instances

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

Retrieve a list of all frpc instances.

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": [
    {
      "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"
    }
  ]
}

Response (visitor):

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

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

---

User Permissions

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

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