设备指纹

服务端 API

查询设备指纹：用客户端 SDK 拿到的 device_token，换取设备标识、设备信息与风险信号。客户端上报失败时，可通过同一接口提交 SDK 原始 geetoken 进行降级分析，详见「fp_query 降级模式」。

接口

MethodPath用途
POST/api/v2/fp_query/{public_key}查询设备指纹

输入从哪里获取

字段用在从哪里获取
public_key路径 /api/v2/fp_query/{public_key}后台。应用公开标识，用于定位应用和地区。不是认证密钥。
secretAuthorization: Bearer <secret>后台。服务端查询认证。
device_token请求体客户端 SDK 接口。

支持的客户端

iOS、Android、Web/H5。

地区限制

每个应用只属于一个地区，由后台配置。请求必须发到该应用所属地区的节点。

地区说明服务节点（HTTPS）
GLB全球https://riskct-global.geelabapi.com
NA北美https://riskct-na.geelabapi.com
EU欧洲https://riskct-eu.geelabapi.com

发到其他地区的节点时，返回 404，message 为 integration not found。

响应信封

Content-Type: application/json。HTTP 状态码与 JSON code 相同。

成功：

{ "code": 200, "data": {}, "message": "Success" }

失败：

{ "code": 400, "data": {}, "message": "Invalid request" }

校验失败时 data 为：

{
  "errors": [
    { "field": "device_token", "reason": "Field required", "type": "missing" }
  ]
}

错误码

HTTP / codemessage含义
400Invalid request请求体不合法，或 device_token 无效
401Invalid bearer token认证失败，到后台核对 secret
403Forbidden应用不可用、未通过白名单，或降级模式未开启
403deactivate / quota_exceeded / manual_deactivate客户产品开关 switch=off；message 为 CustomerProductVersion.status
404integration not foundpublic_key 无效，或请求未打到应用所属地区的节点
429Too many requests降级分析超过应用限流配额
500Internal server error服务端错误

POST /api/v2/fp_query/{public_key}

查询设备指纹。传入客户端 SDK 返回的 device_token，得到设备标识、设备信息与风险信号。

MethodPOST
Path/api/v2/fp_query/{public_key}
AuthAuthorization: Bearer <secret>
Content-Typeapplication/json
SuccessHTTP 200，code=200，message=Success

请求

POST /api/v2/fp_query/{public_key}
Authorization: Bearer <secret>
Content-Type: application/json

Path

字段类型必填含义从哪里获取
public_keystring是应用公开标识后台

Headers

字段必填含义从哪里获取
Authorization是Bearer <secret>，服务端查询认证secret 从后台获取
Content-Type是application/json—

Body

{
  "device_token": "<from-client-sdk>",
  "event_type": "login",
  "event_time": "2026-08-20T10:30:00+08:00"
}
字段类型必填含义从哪里获取
device_tokenstring是普通查询传结果 token；降级分析传 SDK 原始 geetoken，均使用此字段客户端 SDK 接口
event_typestring否业务事件类型，如 login调用方自行填写
event_timestring否事件时间，RFC 3339（需带时区或 Z）调用方自行填写

最小请求体：

{ "device_token": "<from-client-sdk>" }

fp_query 降级模式

客户端 SDK 上报数据失败、未取得结果 token 时，可将 SDK 生成的原始 geetoken 交给业务服务端，通过同一个 POST /api/v2/fp_query/{public_key} 获取设备指纹与风险信号。

请求方式

  • 请求体仍使用 device_token 字段，将 SDK 原始 geetoken 原样填入，无需新增字段或指定模式。
  • 请求地址、Bearer 认证和其他可选参数与普通查询一致，请使用应用所属地区的服务节点。secret 仅保留在业务服务端，不应交给客户端。

全球节点示例（北美、欧洲应用需替换为对应节点）：

curl -sS -X POST "https://riskct-global.geelabapi.com/api/v2/fp_query/{public_key}" \
  -H "Authorization: Bearer {secret}" \
  -H "Content-Type: application/json" \
  -d '{"device_token":"{sdk_raw_geetoken}"}'

响应结构与普通查询一致，见下文「响应 200」。降级模式下，fp_query 成功请求也会计费。

响应 200

{
  "code": 200,
  "data": {
    "request_id": "req_0198c7a1-5b2e-7c10-8d44-1234567890ab",
    "event_id": "evt_0198c7a1-5b2e-7c10-8d44-1234567890ab",
    "fp_detail": {
      "device_id": "GEE4-xxxxxx",
      "version": "1.0"
    },
    "signals": [
      {
        "signal": "CLOUD_PHONE",
        "level": "HIGH",
        "confidence": 0.8
      }
    ],
    "detail": {
      "client_type": "Android",
      "device_basic": {
        "os": "Android",
        "pla": "arm64-v8a",
        "mod": "Pixel 8",
        "osv": "14"
      },
      "ip_info": {
        "ip": "1.1.1.1"
      }
    }
  },
  "message": "Success"
}

data

字段类型含义
request_idstring分析 ID。格式 req_ + UUID v7。普通查询同一结果 token 时相同；降级分析每次请求重新生成。
event_idstring本次查询 ID。格式 evt_ + UUID v7。每次查询值不同。
fp_detailobject设备指纹
signalsarray命中的信号列表，未命中时为 []
detailobject客户端类型、设备信息、IP

fp_detail

字段类型含义
device_idstring设备指纹
versionstring指纹版本，当前为 "1.0"

signals[]

字段类型含义
signalstring信号标识，例如 CLOUD_PHONE
levelstringLOW / MEDIUM / HIGH
confidencenumber0.0–1.0

以下为服务端 API 当前支持的信号取值与说明。

信号一览（40+）

signallevel说明支持的端
BEING_DEBUGGEDHIGH设备存在被调试风险，可进行逆向分析、破解、群控自动化Android, iOS, Web
DEBUG_MODE_OR_TEST_APPLOW设备开启了调试模式或使用 debug/ 破解版本非商店下载的应用包Android, iOS
EMULATORHIGH检测到传统模拟器风险Android, iOS, Web
CLOUD_PHONEHIGH检测到云手机（或 ARM 服务器）风险Android
RUNNING_ON_MACOSMEDIUM检测到 Mac 运行 App 风险iOS
VPN_ENABLEDLOW设备开启 VPN 中Android, iOS
NETWORK_PROXYMEDIUM设备开启网络代理中Android, iOS
INVALID_PACKAGELOW检测到包名篡改或重打包Android, iOS
TOKEN_EXPIREDMEDIUMdevice_token 过期或重复使用Android, iOS, Web
LIMIT_EXCEEDMEDIUM超过限制Android, iOS, Web
SCREEN_SHARINGLOW设备正在进行屏幕分享Android, iOS
VOICE_CONNECTEDLOW设备正在语音通话中Android, iOS
IP_CRAWLER_OR_BOTMEDIUMIP 存在恶意破解或爬虫行为Android, iOS, Web
IP_MALICIOUS_ATTACKHIGHIP 存在恶意攻击行为Android, iOS, Web
IP_SUSPICIOUS_PROXYMEDIUMIP 疑似代理IPAndroid, iOS, Web
IDC_IPMEDIUMIDC/数据中心 IPAndroid, iOS, Web
DEVICE_JAILBREAKHIGHiOS 设备存在越狱行为iOS
DEVICE_ROOTEDHIGHAndroid 设备存在 Root 行为Android
SUSPICIOUS_CUSTOM_ROMHIGHAndroid 设备使用可疑定制 ROMAndroid
SUSPICIOUS_OPEN_SOURCE_ROMHIGHAndroid 设备 ROM 为安卓开源项目Android
BROWSER_COOKIE_FEATURE_DISABLEDMEDIUM浏览器cookie不可用Web
PSEUDO_BROWSER_ENVHIGH伪造的浏览器环境Web
BROWSER_INCOGNITO_MODELOW浏览器处于隐私模式Web
DEVICE_BOOTLOADER_UNLOCKEDHIGH检测到设备 Bootloader 已解锁Android
SUSPICIOUS_DEVICE_RESETHIGH疑似设备重置Android, iOS
SYSTEM_VERSION_TOO_LOWMEDIUM设备系统版本过低Android, iOS
DEVICE_WITHOUT_SIMLOW检测到设备未插 SIM 卡Android, iOS
HOOK_TAMPERING_LOWMEDIUM检测到代码篡改的低风险迹象；评估该信号时请排除应用自身的调试或开发行为iOS, Web
HOOK_TAMPERING_MEDIUMHIGH设备有代码篡改中风险，可篡改代码逻辑Android, iOS, Web
HOOK_TAMPERING_HIGHHIGH设备有代码篡改高风险Android, iOS
SUSPICIOUS_DEVICE_INFO_TAMPEREDHIGH设备存在信息伪造风险，设备属性或指纹不匹配Android, iOS
ANTIDETECT_BROWSERHIGH设备运行在反检测浏览器中Web
APP_CLONE_TOOL_INSTALLEDLOW设备存在安装多开工具风险Android, Web
TAMPER_TOOL_INSTALLEDLOW检测到设备安装了改机工具风险Android, iOS
AUTOMATION_TOOL_INSTALLEDLOW检测到设备安装了群控/自动化工具风险，可规模化黑产操作Android, iOS
REVERSE_ENGINEERING_TOOL_INSTALLEDLOW检测到设备安装逆向工具风险Android, iOS, Web
NETWORK_TAMPER_TOOL_INSTALLEDLOW设备存在使用网络篡改工具风险Android, iOS
GAME_TAMPER_TOOL_INSTALLEDLOW设备存在使用游戏修改器工具风险Android, iOS
VIRTUAL_LOCATION_TOOL_INSTALLEDLOW检测到设备安装了虚拟定位风险Android, iOS
RUNNING_IN_VIRTUAL_MACHINEHIGH当前设备处于虚拟机环境中Android, iOS, Web
RUNNING_IN_CLONED_APPHIGH当前处于多开环境中Android, iOS
USING_DEVICE_TAMPERING_TOOLHIGH当前正使用改机或风险工具Android
USING_AUTOMATION_TOOLHIGH当前正使用群控或自动化工具Android, iOS
USING_REVERSE_ENGINEERING_TOOLHIGH当前正使用逆向篡改工具Android
USING_VIRTUAL_LOCATIONHIGH当前正使用虚拟定位工具Android, iOS
RUNNING_IN_SYSTEM_CLONEDLOW设备系统多开风险Android

detail

字段类型含义
client_typestringAndroid / iOS / Web/H5
device_basicobject设备基础信息，结构随 client_type 变化
ip_infoobject{ "ip": "<string>" }

Android / iOS 的 device_basic：

{
  "os": "Android",
  "pla": "arm64-v8a",
  "mod": "Pixel 8",
  "osv": "14"
}
字段含义
os操作系统
pla架构
mod型号
osv系统版本

Web/H5 的 device_basic：

{
  "browser": { "name": "Chrome", "version": "145.0.0.0", "major": "145" },
  "device": { "model": "Macintosh", "vendor": "Apple" },
  "os": { "name": "macOS", "version": "10.15.7" }
}

错误

HTTP 状态码等于 code。message 为下表中的精确字符串。

HTTPmessagedata含义
400Invalid request{ "errors": [ { "field", "reason", "type" } ] }缺字段、类型错误或 event_time 非法
400Invalid request{ "errors": [{ "field": "device_token", "reason": "Invalid token", "type": "value_error" }] }device_token 无效
401Invalid bearer token{}认证失败
403Forbidden{}应用不可用、未通过白名单，或降级模式未开启
403deactivate / quota_exceeded / manual_deactivate{}客户产品开关 switch=off；message 为当时的 CustomerProductVersion.status，不是 Forbidden
404integration not found{}public_key 无效，或请求未打到应用所属地区的节点
429Too many requests{}降级分析超过应用分钟或小时限流配额
500Internal server error{}服务端错误
{
  "code": 400,
  "data": {
    "errors": [
      { "field": "device_token", "reason": "Field required", "type": "missing" }
    ]
  },
  "message": "Invalid request"
}
{
  "code": 401,
  "data": {},
  "message": "Invalid bearer token"
}

示例

{public_key}、{secret} 从后台复制；{device_token} 用客户端 SDK 返回值；请求发到应用所属地区的节点。

curl -sS -X POST "https://{host}/api/v2/fp_query/{public_key}" \
  -H "Authorization: Bearer {secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "{device_token}",
    "event_type": "login",
    "event_time": "2026-08-20T10:30:00+08:00"
  }'

合规与隐私

Previous Page

On this page

接口输入从哪里获取支持的客户端地区限制响应信封错误码POST /api/v2/fp_query/{public_key}请求PathHeadersBodyfp_query 降级模式请求方式响应 200datafp_detailsignals[]信号一览（40+）detail错误示例