Open-Source Disclaimer and Reading Guide
Please respect the spirit of open source and exercise your own judgment. If you agree with these principles, continue with the documentation below.
System Requirements and Deployment
The GuYi Access Pro v2026.10.6 backend is built with native PHP and is lightweight enough to run in any web environment that meets the basic requirements.
- PHP version: 7.2 or later is recommended (PDO and JSON extensions required)
- Database: MySQL 5.6 or later
Quick Deployment Steps:
Upload the source code to your website root directory, then visit http://your-domain/install.php. Follow the on-screen instructions to enter your database connection details and click Install. The required tables will be created automatically.
Communication Protocol and Global Rate Limits
The current server exposes a unified JSON API for client verification. Send HTTPS POST requests to the actual PHP API URL provided in the application dashboard; do not assume the static website domain is also the API domain.
Content-Type: application/json
The server applies rate limits by IP address and returns HTTP 429 with a JSON error when the limit is exceeded. Clients should set connection/read timeouts and retry later after a rate-limit response. Avoid frequent polling.
License Key Verification (Based on the Current Server Source)
The current Verify.php does not validate the legacy timestamp and sign fields. Basic verification uses app_key and card_code; a stable device_hash is also recommended. Do not copy examples of the legacy signature algorithm.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
app_key | String | Required | The 64-character hexadecimal AppKey generated when an application is created in the dashboard. The current encryption implementation decodes it into a 32-byte AES key. |
card_code | String | Required for verification | The license key entered by the user. If omitted, the API returns application update information and public cloud variables instead of verifying a key. |
device_hash | String | Recommended | A stable device identifier for the current installation. The server binds the key to this string. If omitted, the request source IP is MD5-hashed as a fallback, which may cause unstable binding when the network changes. |
custom_data | String | Optional | Custom text associated with the license key. To store JSON, serialize it to a string before sending it. |
action | String | Optional | License key verification is the default and this field can be omitted. Use another action only for an administrative operation explicitly implemented by the server. |
Important: Client Access Restrictions on the Current Server
Database::verifyCard() checks the HTTP User-Agent. Verification proceeds only if it contains [IOS_WEBAPP_VERIFIED] or the license key has browser_whitelist=1. The generic SDK examples below do not forge this marker. For regular desktop or mobile clients, enable the relevant license-key browser whitelist according to your policy, or adjust the server-side client authorization logic; otherwise, requests will be rejected.Response Format and Success Checks
A decrypted successful response has the structure {code, msg, data}. The data object may contain expire_time, custom_data, update, and variables. Check whether the JSON field code === 200 to determine business-level success. Some error responses are unencrypted JSON, so do not assume that every response contains encrypted_data.
Active Devices and Heartbeat Updates
The current source code does not implement a separate action=heartbeat branch. When an already-bound device submits the same application key and the same device_hash again, the server refreshes the active device’s last_heartbeat. Do not treat the legacy action=heartbeat as a separate endpoint. Poll at a reasonable interval and observe the per-IP rate limit.
Self-Service Device Unbinding
Users can unbind a device themselves when switching computers. The system deducts a specified penalty period to reduce manual support requests.
- Parameters:
action=unbind,card_code=TARGET_CARD_CODE - Penalty: A successful call to this endpoint deducts 12 hours from the license key’s remaining validity period.
- How it works: After a successful call, the system clears the device record for that license key. When the user signs in and verifies the key on a new computer, the new device is bound automatically.
Software Updates and Cloud Variables
When a valid app_key is provided without card_code, the API returns application update information and public cloud variables. After successful license-key verification, the response’s data object may also include the key’s expiration time, custom data, update information, and application variables.
custom_data is a custom string associated with a license key, not a standalone variable endpoint. Serialize any object as JSON text before sending it. Do not treat an AppKey embedded in a client or cloud variables as secrets that cannot be extracted.
Automated Key Distribution Platforms and Admin API
These endpoints are intended for automated key distribution platforms and bot-based administration. Requests must include api_token for authentication.
1. Generate License Keys in Bulk (For Distribution Platforms)
- Parameters:
action=generate,api_token=YOUR_TOKEN,app_id=YOUR_APP_ID,type=dayortype=custom,num=COUNT - Optional parameters:
pre=PREFIX,note=NOTE,custom_hours=HOURS(used withtype=custom) - Response: The response includes a
card_stringfield containing newline-separated license keys that can be imported directly into a distribution platform.
2. Force Logout and Unbind (No Time Deduction)
- Parameters:
action=kick,api_token=YOUR_TOKEN,card_code=TARGET_CARD_CODE - Purpose: An administrator can forcibly clear the target key’s device binding without deducting any penalty time.
3. Ban, Unban, and Permanently Delete
- Add to blacklist:
action=ban(suspends the key and prevents the user from signing in) - Remove ban:
action=unban(restores normal status) - Permanently delete:
action=del_card(permanently removes the key from the database)
Active Defense and Cloud Blacklisting (High-Risk Operations)
This endpoint strengthens software protection. When a client detects CE / OD, packet-capture tools, or memory injection in the user’s environment, it can call this API to blacklist the associated device in the cloud.
device_hash and public IP address are added to the cloud blacklist, blocking further access.- Action:
action=ban_machine(oraction=blacklist) - Required parameters:
device_hash=TARGET_DEVICE_HWID - Optional parameters:
reason=REASON
AES-256-GCM Response Decryption
When API encryption is enabled in the dashboard and the server is given a valid AppKey while building the response, the outer response contains encrypted_data. Base64-decode this value, then split the payload in the order used by the server.
- Key: The current server hex-decodes the 64-character hexadecimal
app_keyinto a 32-byte AES-256 key. It does not useapi_secret. - First 12 bytes: IV (initialization vector).
- Next 16 bytes: GCM tag (authentication tag).
- Remaining bytes: Ciphertext. Some language-specific crypto libraries require the tag to follow the ciphertext, so the examples rearrange the buffer as required by each library.
- Authentication: Always verify the GCM tag. Reject the response if decryption or authentication fails; do not proceed.
- Handling Error Responses: Some current error paths build a response without an AppKey and therefore return plain-text JSON in the form
{code, msg, data}. Clients must support both response formats.
Security Note: The AppKey serves as both a client-visible identifier and a symmetric decryption key. If embedded in a desktop or mobile application, it may be extracted through reverse engineering; obfuscation cannot guarantee secrecy. Never put the admin api_token in a client.
Client Client Integration Examples in 8 Languages
The examples below reflect the request fields, response structure, and AES-GCM byte layout in the current repository. Replace the API URL, AppKey, license key, and stable device identifier, then install the dependencies required for your language.
Read “Client Access Restrictions” above first. The current server may require the license key’s browser whitelist to be enabled; otherwise, even a correctly formatted request from a generic SDK may be rejected.
Global Status Codes
| Business Code | Meaning | Recommended Client Handling |
|---|---|---|
200 | Verification or request succeeded | Proceed only after decryption and parsing complete and the business code is 200. |
400 | A required parameter is missing, no license key was supplied, or an action parameter is invalid | Check the required fields and parameter names. |
403 | The AppKey is incorrect, the application is unavailable, the license key is invalid or banned, the device conflicts with an existing binding, or a client policy was triggered | Display the server’s msg and deny access. Do not treat an error response as success. |
404 | The specified license-key record does not exist for some administrative operations | Check the target license key and application. |
429 | The per-IP request rate limit was exceeded | Reduce the request rate and retry after a short delay. |
500 | Internal server error | Check the server logs and database connection. |
Note: code is the business code in the JSON response and does not necessarily match the HTTP status code. Parse the response safely before checking the business code, and log transport-level statuses such as HTTP 429 separately.