GuYi Access Developer Documentation

Based on the currently published source code, this guide covers the API, multilingual client integration examples, and AES-256-GCM response decryption.

Developer Community

For questions about cross-language integration, request debugging, or AES-256-GCM decryption, join the developer community on Telegram: @GuYi0u0

Join the Community

Open-Source Disclaimer and Reading Guide

Important: This is a non-profit open-source project, not a paid commercial product. The core engine is open source to share knowledge and support learning and collaboration. Before reading this guide and integrating the project, please understand the following principles:
1. Open Source Does Not Include One-on-One Handholding
Open source is not a commercial service. Maintainers are not obligated to provide step-by-step tutorials from scratch or ready-made code for every programming language.
2. Basic Technical Skills Are Required
This guide describes the communication protocol, API parameters, and AES-256-GCM response format implemented in the current source. Cross-platform integration requires basic programming skills and the ability to debug requests and analyze logs independently.
3. Use Open-Source Resources Responsibly
If you expect an open-source project to provide every customization and one-on-one support for free, this project may not be a good fit. We welcome technical discussion and ask that you respect the time and effort of maintainers.
4. Disclaimer (Provided “As Is”)
The source code and documentation are provided “as is,” without warranties of any kind, express or implied. The authors are not liable for losses or disputes arising from use of this project.

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.

POST /Verifyfile/api.php
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

ParameterTypeRequiredDescription
app_keyStringRequiredThe 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_codeStringRequired for verificationThe license key entered by the user. If omitted, the API returns application update information and public cloud variables instead of verifying a key.
device_hashStringRecommendedA 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_dataStringOptionalCustom text associated with the license key. To store JSON, serialize it to a string before sending it.
actionStringOptionalLicense 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

The current 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.

Security Warning: The repository currently contains a hard-coded default admin API token. Before deployment, replace it with a strong random token and load it from secure configuration or an environment variable. Never include the admin token in client applications or public documentation.

1. Generate License Keys in Bulk (For Distribution Platforms)

  • Parameters: action=generate, api_token=YOUR_TOKEN, app_id=YOUR_APP_ID, type=day or type=custom, num=COUNT
  • Optional parameters: pre=PREFIX, note=NOTE, custom_hours=HOURS (used with type=custom)
  • Response: The response includes a card_string field 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.

Strict enforcement: Once triggered, the associated device’s device_hash and public IP address are added to the cloud blacklist, blocking further access.
  • Action: action=ban_machine (or action=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.

{ "encrypted_data": "Base64(IV + Tag + Ciphertext)" }
  • Key: The current server hex-decodes the 64-character hexadecimal app_key into a 32-byte AES-256 key. It does not use api_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 CodeMeaningRecommended Client Handling
200Verification or request succeededProceed only after decryption and parsing complete and the business code is 200.
400A required parameter is missing, no license key was supplied, or an action parameter is invalidCheck the required fields and parameter names.
403The 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 triggeredDisplay the server’s msg and deny access. Do not treat an error response as success.
404The specified license-key record does not exist for some administrative operationsCheck the target license key and application.
429The per-IP request rate limit was exceededReduce the request rate and retry after a short delay.
500Internal server errorCheck 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.

Code copied to the clipboard!