All Products
Search

This Product

    ID Verification:Server-side API operation

    Document Center

    ID Verification:Server-side API operation

    Last Updated:Feb 26, 2026

    This topic describes how to configure your server for FACE_GUARD_PRO.

    API description

    • API operation: FaceGuardRisk

    • Request method: POST or GET

    • Protocol: HTTPS

    • Important

      FACE_GUARD_PRO is billed per successful query. To avoid duplicate charges, do not submit the same Device Token for a query more than once after a successful response.

    • This API operation has a dedicated QPS limit. For more information, see QPS limits for ID Verification server-side API operations.

    • Global endpoints:

      Note

      • An internal network is a private communication network between Alibaba Cloud products within the same region. If your business server is deployed in an Alibaba Cloud region, you can use the internal same-region endpoint to access the ID Verification service. This provides more secure and stable network communication.

      • To meet data collection compliance requirements in different regions, Device Guard provides different data reporting sites. Data is isolated between these sites.

        The client specifies a reporting site by setting the CustomUrl and CustomHost parameters. The server-side must use the domain name that corresponds to the site reported by the client to query and retrieve detailed information.

      Singapore

      • Public network: cloudauth-intl.ap-southeast-1.aliyuncs.com

      • Internal network: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

      Indonesia

      • Public network: cloudauth-intl.ap-southeast-5.aliyuncs.com

      • Internal network: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

      China (Hong Kong)

      • Public network: cloudauth-intl.cn-hongkong.aliyuncs.com

      • Internal network: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

      US (Silicon Valley)

      • Public network: cloudauth-intl.us-west-1.aliyuncs.com

      • Internal network: cloudauth-intl-vpc.us-west-1.aliyuncs.com

      Germany (Frankfurt)

      • Public network: cloudauth-intl.eu-central-1.aliyuncs.com

      • Internal network: cloudauth-intl-vpc.eu-central-1.aliyuncs.com

      Malaysia (Kuala Lumpur)

      • Public endpoint: cloudauth-intl.ap-southeast-3.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com

    Online testing and integration

    Note

    Before you debug and integrate an API operation, see Debug and integrate server-side API operations using OpenAPI Explorer for information about how to call API operations and obtain SDKs and sample code in OpenAPI Explorer.

    You can run this API operation in OpenAPI Explorer to test it and generate SDK sample code.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product code. Set this to the static field FACE_GUARD_PRO.

    FACE_GUARD_PRO

    MerchantBizId

    String

    Yes

    A unique business identifier that you define. It is used for troubleshooting. The identifier can be up to 32 characters in length and can contain letters and digits. Ensure that the identifier is unique.

    e0c34a77f5ac40a5aa5e6ed2********

    DeviceToken

    String

    Yes

    The deviceToken obtained from the client SDK.

    Tk9SSUQuMS*****************ZDNmNWY5NzQxOW1o

    BizId

    String

    No

    The unique ID of the current authentication. It is used with FACE_GUARD_PRO for verification during queries.

    1000******0001

    Response parameters

    Name

    Type

    Description

    Example

    RequestId

    String

    The request ID.

    130A2C10-B9EE-4D84-88E3-5384********

    Code

    String

    The return code. A value of 200 indicates that the API operation responded successfully. To determine the detailed authentication result, expand the Return codes section below.

    Success

    Message

    String

    A detailed description of the return code.

    success

    Result.TransactionId

    String

    The unique identifier for the entire authentication flow.

    e0c34a77f5ac40a5aa5e6ed2********

    Result.RiskTags

    String

    The device risk tags. Multiple risk tags are separated by commas (,). To learn more about the risk tags and their meanings, expand the Risk tags (RiskTags) section below.

    ROOT,VPN,HOOK

    Result.RiskExtends

    String

    Extended information. This is empty by default.

    {
  "code": "Success",
  "message":"success"
  "umid":"07d3295d3d597b425d102a7f********",
  "sip":"198.51.100.1",
  "durationMs" : 4968931
  "queryCount":1,
  "querySessionCount":1,
  "queryUmidCount":1
  "platform":"Android
}

    Result.GuardRiskScore

    Double

    The device risk probability predicted by the Face Guard algorithm. A higher score indicates a higher device risk.

    Valid values: 0 to 100.

    99

    Click to view: Return codes

    HTTP status code

    Code

    Message description

    200

    Success

    The request is successful.

    400

    MissingParameter

    The parameter cannot be empty.

    InvalidParameter

    Invalid parameter.

    401

    Forbidden.ExceptionRepeatedInvoke

    The number of repeated abnormal calls exceeds the limit.

    403

    Forbidden.RAMUserAccessDenied

    Grant the Resource Access Management (RAM) user the AliyunAntCloudAuthFullAccess permission. For more information, see Authorize RAM users to access the service.

    Forbidden.AccountAccessDenied

    Make sure that you have activated ID Verification and your account has no overdue payments.

    Throttling.Api

    The API call is throttled.

    429

    SuspiciousActivity

    Security policy restriction. Try again later.

    500

    InternalError

    An internal system error occurred. Contact engineers for troubleshooting.

    503

    ServiceUnavailable

    The service is unavailable. Contact engineers for troubleshooting.

    Click to view: Risk tags (RiskTags)

    Threat category

    Risk tag

    Description

    Device threat (Native SDK)

    ROOT

    The device is suspected of being rooted or jailbroken.

    HOOK

    The device is suspected of being hooked.

    VPN

    The device is suspected of using a VPN.

    Emulator

    The device is suspected of being an emulator.

    SystemVirtual

    The device is running multiple instances of the OS.

    Important

    Only supported on Android

    ThirdVirtual

    The device is running multiple instances of a third-party application.

    Important

    Only supported on Android

    AdbModel

    Developer mode is enabled on the device.

    Important

    Only supported on Android

    DebugModel

    Debug mode

    NoSimCard

    No SIM card is inserted in the device.

    VirtualVideo

    A virtual video tool is installed.

    UsingVirtualVideo

    A virtual video tool is in use.

    MirroredScreen

    The screen is being recorded or captured.

    Important

    Only supported on iOS

    RiskROM

    High-threat custom ROM.

    Important

    Only supported on Android

    UnusualROM

    Unconventional ROM.

    Important

    Only supported on Android

    AutoOperation

    Automated operation.

    BlackTool

    A high-threat tool is installed.

    CloudPhone

    Cloud phone.

    Important

    Only supported on Android

    BootUnLock

    The device bootloader is unlocked.

    Important

    Only supported on Android

    BootCountLittle

    The device has been started a few times.

    Important

    Only supported on Android

    ChargeScreenBright

    The phone screen stays on while charging.

    Important

    Only supported on Android

    ChargeScreenNoSecure

    The phone has no screen lock password while charging.

    Important

    Only supported on Android

    ChargeWithUsb

    The phone is charging via USB.

    Important

    Only supported on Android

    FakeDevice

    Device modification, including but not limited to tampering with the device model or device features.

    AbnormalPort

    Abnormal device port.

    Important

    Only supported on Android

    Device threat (Web SDK)

    VirtualBrowser

    Suspected virtual browser.

    VirtualCamera

    A virtual camera is suspected to be installed.

    UsingVirtualCamera

    A virtual camera is suspected to be in use.

    AutoOperation

    Suspected automation tool.

    BrowserTampered

    Browser parameters are suspected to be tampered with.

    Debugger

    Page JS is suspected to be under debugging.

    CloudPhone

    Suspected cloud phone environment

    WebCrawler

    Suspected malicious web crawler or protocol-based batch calling

    CookieDisabled

    Cookies are disabled.

    Incognito

    The browser is in incognito mode.

    MediaHook

    The browser's video stream API is hooked.

    NoRefer

    The face verification page has no referrer source.

    Note

    This tag is used with ID Verification. It is not available for standalone Device Guard integration.

    UnmatchOsUrl

    The verification page URL does not match the device.

    Note

    This tag is used with ID Verification. It is not available for standalone Device Guard integration.

    DeviceToken threat

    TokenIsNull

    The deviceToken is empty.

    TokenTampered

    The deviceToken is tampered with.

    TokenInvalid

    The deviceToken is invalid.

    TokenExpired

    The deviceToken has expired (valid for 7 days).

    General

    BizIdNotMatch

    The bizId passed in by the business does not match the bizId attached to the token. This is common in attacks such as token replacement or impersonation.

    Note

    If this occurs frequently, first check the consistency between the bizId in the getDeviceToken call in the client integration link and the bizId passed to the Device Guard query API operation.

    DeviceBadNet

    Weak network environment (Device Guard initialization failed).

    Note

    If this occurs frequently, first check the client integration link.

    This is usually because the client initialization and the getDeviceToken API operation are not integrated according to the standard time series chart in the official documentation. Adjust the token acquisition timing with reference to the official documentation.

    ReportingGap

    The Device Guard is not reporting data.

    Note

    If this occurs frequently, first check the client integration link.

    This is usually because the client initialization and the getDeviceToken API operation are not integrated according to the standard time series chart in the official documentation. Adjust the token acquisition timing with reference to the official documentation.

    Business scenario

    HighRiskEnv

    High-threat environment from the cyber underground economy chain. Comprehensively judged as a high-threat environment from the cyber underground economy chain.

    Note

    This is a comprehensive tag based on the accumulated online attack and defense experience, and the result of a multi-dimensional conditional judgment.

    MiddleRiskEnv

    Medium-threat environment from the cyber underground economy chain. Comprehensively judged as a medium-threat environment from the cyber underground economy chain.

    Note

    This is a comprehensive tag based on the accumulated online attack and defense experience, and the result of a multi-dimensional conditional judgment.

    PermittedDevice

    Whitelisted device.

    Note

    This device is set as a whitelisted device. The default GuardRiskScore is 0.

    BlackListedDevice

    Blacklisted device.

    Note

    This device has been identified as having repeated attack behaviors. The default GuardRiskScore is 100.

    Mining class based on large language models (LLMs)

    Note

    Only the FACE_GUARD_PRO version supports this type of tag.

    QwenSeekRisk

    The LLM determines that a high-threat environment exists in the verification process.

    Other

    NoRisk

    The device threat is low.

    The NoRisk tag is returned when the system does not detect any of the above threats.

    NoTag

    No data returned.

    The NoTag tag is automatically returned when the ID Verification system cannot obtain threat tags due to an exception.

    Click to view: Result.RiskExtends field

    Field

    Meaning

    Detailed description

    code

    Token status code

    • 200: The token is normal.

    • 401: The data in the token is abnormal.

    • 404: The data format in the token is abnormal.

    • 407: The token has expired (valid for 7 days).

    • 408: The token or reported data has been tampered with.

    • 500: An unknown token exception occurred.

    message

    Token error message

    The error message related to the token. This field has a value when the code is not 200.

    umid

    Unique device ID

    07d3295d3d597b425d102a7f********

    platform

    Device platform

    • Android

    • iOS

    • Harmony

    • Web

    sip

    Client IP address

    198.51.100.1

    durationMs

    The time difference between the query and the client-side initialization, in milliseconds.

    4968931

    queryCount

    The number of times the token was used for queries on the current day.

    1

    querySessionCount

    The number of times the session associated with the token was used for queries on the current day.

    2

    queryUmidCount

    The number of times the device was used for queries on the current day.

    2