All Products
Search

This Product

    ID Verification:Server-side API operations

    Document Center

    ID Verification:Server-side API operations

    Last Updated:Dec 01, 2025

    This topic describes how to set up the server for FACE_GUARD.

    API description

    • API operation: FaceGuardRisk

    • Request methods: POST and GET

    • Transport protocol: HTTPS

    • Important

      FACE_GUARD is billed based on the number of successful queries. To avoid duplicate charges, do not resubmit a query for a device token that has already succeeded.

    • QPS limit: This API is subject to an exclusive queries per second (QPS) limit. For more information, see ID Verification server-side API QPS limits.

    • Global access endpoints:

      Note

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

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

        The client specifies different reporting sites by setting CustomUrl and CustomHost. The server must access the domain name that corresponds to the site reported by the client to retrieve the details.

      China (Hong Kong)

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

      • Internal same-region endpoint: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

    Online debugging and integration

    Note

    Before you debug and integrate, read the Use OpenAPI Explorer to debug and integrate server-side API operations document. It explains how to call API operations on the OpenAPI platform and how to obtain the SDK and its sample code.

    You can run this API operation in OpenAPI Explorer for debugging. You can also generate an SDK code sample for this operation.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

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

    FACE_GUARD

    MerchantBizId

    String

    Yes

    A custom unique business identifier. It is used to locate and troubleshoot issues. The identifier can be a combination of letters and digits up to 32 characters long. Ensure that it is unique.

    e0c34a77f5ac40a5aa5e6ed20c35****

    DeviceToken

    String

    Yes

    The deviceToken obtained from the client SDK.

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

    BizId

    String

    No

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

    1000******0001

    Response parameters

    Name

    Type

    Description

    Example

    RequestId

    String

    The request ID.

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

    Code

    String

    The return code. A value of Success indicates that the request was successful. For more information about other possible values, 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.

    e0c34a77f5ac40a5aa5e6ed20c35****

    Result.RiskTags

    String

    The device risk tags. Multiple risk tags are separated by commas (,). For more information 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": 200
  "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 Device Guard algorithm. A higher score indicates a higher device risk.

    Valid values: 0 to 100.

    99

    Expand to view: Return codes

    HTTP status code

    Code

    Message description

    200

    Success

    The request was successful.

    400

    MissingParameter

    The parameter cannot be empty.

    InvalidParameter

    The parameter is invalid.

    401

    Forbidden.ExceptionRepeatedInvoke

    The number of repeated abnormal calls exceeds the limit.

    403

    Forbidden.RAMUserAccessDenied

    You must grant the AliyunAntCloudAuthFullAccess permission to the Resource Access Management (RAM) user. For more information, see Grant permissions to a RAM user to access services.

    Forbidden.AccountAccessDenied

    Make sure that you have activated ID Verification and that your account does not have an overdue payment.

    Throttling.Api

    The API call is blocked by throttling.

    429

    SuspiciousActivity

    The request is blocked by a security policy. Try again later.

    500

    InternalError

    An internal system error occurred. Contact engineers for troubleshooting.

    503

    ServiceUnavailable

    The service is unavailable. Contact engineers for troubleshooting.

    Expand to view: Risk tags (RiskTags)

    Threat category

    Threat tag

    Description

    Device threats (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 system is running multiple instances.

    Important

    Only supports Android.

    ThirdVirtual

    The device is running multiple third-party instances.

    Important

    Only supports Android.

    AdbModel

    Developer mode is enabled on the device.

    Important

    Only supports 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 being used.

    MirroredScreen

    Screen recording or screen capture is active.

    Important

    Only supports iOS.

    RiskROM

    This custom ROM is considered high-risk.

    Important

    Only supports Android.

    UnusualROM

    Unconventional ROM.

    Important

    Only supports Android.

    AutoOperation

    Automated operation.

    BlackTool

    An important tool is installed.

    CloudPhone

    Cloud phone.

    Important

    Only supports Android.

    BootUnLock

    Device boot is unlocked.

    Important

    Only supports Android.

    BootCountLittle

    The device has been started a few times.

    Important

    Only supports Android.

    ChargeScreenBright

    The phone screen stays on while charging.

    Important

    Only supports Android.

    ChargeScreenNoSecure

    The phone has no lock screen password while charging.

    Important

    Only supports Android.

    ChargeWithUsb

    The phone is charging via USB.

    Important

    Only supports Android.

    FakeDevice

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

    AbnormalPort

    The device port is abnormal.

    Important

    Only supports Android.

    Device threats (Web SDK)

    VirtualBrowser

    Suspected virtual browser.

    VirtualCamera

    Suspected installation of a virtual camera.

    UsingVirtualCamera

    Suspected use of a virtual camera.

    AutoOperation

    Suspected automation tool.

    BrowserTampered

    Suspected tampering of browser parameters.

    Debugger

    Suspected debugging of page JS.

    CloudPhone

    Suspected cloud phone environment.

    WebCrawler

    Suspected malicious crawler/protocol-based invocation.

    CookieDisabled

    Cookies are disabled.

    Incognito

    The browser is in incognito mode.

    MediaHook

    The browser video stream API is hooked.

    NoRefer

    The face authentication page has no referrer source.

    Note

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

    UnmatchOsUrl

    The authentication page URL and the device do not match.

    Note

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

    DeviceToken threats

    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 by the business does not match the bizId binding in the token. This is common in attack methods such as token replacement or impersonation.

    Note

    If this occurs at a high rate, we recommend first checking the consistency of the bizId in the getDevieToken call and the bizId passed to the Device Guard query API operation in the client integration link.

    DeviceBadNet

    Weak network environment (Device Guard initialization failed).

    Note

    If this occurs at a high rate, we recommend first checking the client integration link.

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

    ReportingGap

    Device Guard data collection reporting is missing.

    Note

    If this occurs at a high rate, we recommend first checking the client integration link.

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

    Business scenario

    HighRiskEnv

    Important fraud environment. Comprehensively judged as an important fraud environment.

    Note

    This is a comprehensive tag based on accumulated online attack and defense experience, resulting from a multi-dimensional combination of conditional judgments.

    MiddleRiskEnv

    Medium-threat fraud environment. Comprehensively judged as a medium-threat fraud environment.

    Note

    This is a comprehensive tag based on accumulated online attack and defense experience, resulting from a multi-dimensional combination of conditional judgments.

    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 a system exception.

    Expand to view: Result. RiskExtends field descriptions

    Field

    Meaning

    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 is 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

    The platform where the device is located

    • 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 has been queried on the current day.

    1

    querySessionCount

    The number of times the session associated with the token has been queried on the current day.

    2

    queryUmidCount

    The number of times the device has been queried on the current day.

    2