Server API

Purpose

fp_query is used to query device fingerprint identification results.

The caller must first obtain the server-returned gee_token through client_report, then pass that gee_token to fp_query to obtain the final:

• fp fingerprint value
• risk_code risk codes
• risk_label risk labels
• client_ip client IP
• client_type client type
• access_list access list hit information

Integration Flow

The standard call sequence is as follows:

1. The client collects fingerprint data and calls client_report.
2. The server returns a new gee_token.
3. The caller passes the gee_token, private_key, and ts to fp_query.
4. The server returns the final query result.

Notes:

• fp_query only accepts the gee_token returned by client_report.
• Do not pass the original client token directly to fp_query.

Request Information

Request Method

POST

Request URL

/api/v1/fp_query/{app_id}

Path Parameters

Request Body

{
  "gee_token": "string",
  "private_key": "string",
  "ts": 1712345678
}

Field description:

Successful Response

Response Format

{
  "status": "success",
  "code": 0,
  "data": {
    "fp": "fp-value",
    "risk_code": [20400, 20606],
    "risk_label": ["BEING_DEBUGGED", "BROWSER_INCOGNITO_MODE"],
    "client_ip": "1.1.1.1",
    "client_type": "Web/H5",
    "access_list": {
      "hit": false,
      "list_type": "none",
      "identity_type": ""
    }
  }
}

Field Description

access_list Field Description

The access_list structure is as follows:

{
  "hit": false,
  "list_type": "none",
  "identity_type": ""
}

Field description:

Common examples:

• No hit: {"hit": false, "list_type": "none", "identity_type": ""}
• Blacklist hit: {"hit": true, "list_type": "black", "identity_type": "fingerprint"}

client_type Return Values

The current API converts internal client type codes into readable text:

Call Examples

Request Example

curl -X POST 'https://your-domain/api/v1/fp_query/test-app' \
  -H 'Content-Type: application/json' \
  -d '{
    "gee_token": "output-gee-token-from-client-report",
    "private_key": "private-key",
    "ts": 1712345678
  }'

Response Example

{
  "status": "success",
  "code": 0,
  "data": {
    "fp": "GEE3-01-xxxxxxxx",
    "risk_code": [20400, 20606],
    "risk_label": ["BEING_DEBUGGED", "BROWSER_INCOGNITO_MODE"],
    "client_ip": "1.1.1.1",
    "client_type": "Web/H5",
    "access_list": {
      "hit": false,
      "list_type": "none",
      "identity_type": ""
    }
  }
}

risk_code Description

risk_code indicates the risk items detected for the device or environment. Multiple values may be returned at the same time.

Return rules:

• risk_code is an integer array.
• risk_label corresponds one-to-one with risk_code in order.
• A single query may hit multiple risk codes.
• If no risk is hit, risk_code may be an empty array [].

Example:

{
  "risk_code": [20400, 20606],
  "risk_label": ["BEING_DEBUGGED", "BROWSER_INCOGNITO_MODE"]
}

The current risk codes are described below.

Basic

Device / Runtime Environment

Tampering / Automation / Reverse Engineering

Hook / Information Tampering

Debugging / Interaction Risks

Network Environment

Root / Jailbreak / System Risks

Browser Environment

Notes:

• In the official admin console, it is recommended to display both risk_code and risk_label.
• The meaning of risk codes may expand as rules are added. Callers should handle them as values that may return multiple entries.
• For unknown risk codes, risk_label may be an empty string.

Error Description

Business Error Response Format

For business errors, the HTTP status code is usually still 200, and the response format is as follows:

{
  "status": "error",
  "code": -40000,
  "msg": "param error",
  "desc": {}
}

Common Error Codes

private_key Mismatch

{
  "status": "error",
  "code": -40003,
  "msg": "private_key mismatch",
  "desc": {
    "app_id": "test-app"
  }
}

Troubleshooting:

• Check whether private_key corresponds to the current app_id.
• Check whether the wrong application configuration was used.

Application Does Not Exist or Is Not Visible in the Current Environment

{
  "status": "error",
  "code": -40004,
  "msg": "app not found",
  "desc": {
    "app_id": "test-app"
  }
}

Troubleshooting:

• Check whether app_id is correct.
• Check whether the application has been deleted.
• Check whether the current deployment environment allows access to this application.

The Input Is Not the Server-Returned gee_token

{
  "status": "error",
  "code": -40000,
  "msg": "param error",
  "desc": {
    "field": "token",
    "reason": "geetoken required",
    "crypt_type": 10
  }
}

Troubleshooting:

• Check whether the original client token was passed directly to fp_query.
• Confirm that the input is the gee_token returned by client_report.

Internal System Exception

{
  "status": "error",
  "code": -50000,
  "msg": "runtime error",
  "desc": {
    "type": "异常类型文本"
  }
}

Parameter Validation Errors

If the request body is missing fields or contains fields with incorrect types, the API directly returns 422 and does not use the business error wrapper.

Common scenarios:

• Missing gee_token
• Missing private_key
• ts is not an integer

Integration Recommendations

It is recommended to integrate as follows:

1. Use client_report and fp_query as a pair of APIs.
2. Only pass the gee_token returned by client_report to fp_query.
3. Ensure that app_id and private_key come from the same application.
4. Use a current timestamp generated by the server for ts to avoid obviously stale data.
5. Use risk_code + risk_label as business decision inputs. It is not recommended to rely on a single field only.