Verify Endpoint v2.0

This is the information for a superseded version of the Verify Endpoint. For information about the most recent Verify endpoint, see Server-Side Instructions

Overview

The Arkose Labs Fraud Detection and Prevention Platform (Arkose Labs Platform) needs client-side and server-side setup.

The user initiates processing by logging in to your system. A call is made to the Arkose Labs Server to establish credentials and check identity. An Enforcement Challenge (EC) is displayed if it is considered necessary by the Arkose Labs Platform. The user response to the EC is handled by the client-side. It is then passed to your server-side processing, which then calls the Arkose Labs Verify Endpoint. The response from the Arkose Labs Verify Endpoint is then passed to your server-side processing, which decides what action to take, based on the response.

This guide includes server-side set up information.

You must also complete one or more of the client-side set up processes to enable the Arkose Labs Platform.

Fig 1. Flow of information for Arkose Labs Platform

Validate the Enforcement Challenge From Your Server

For security purposes, calls to the Verify Endpoint must come from a server.

The Verify Endpoint is used to verify ECs completed by a user. When you make a request to the Verify Endpoint you have a choice to receive either:

  • A binary response containing only 1 or null and no other information

or

  • A full JSON response containing:

    • Whether the user is considered legitimate or not

    • If the user solved the Arkose Labs Enforcement Challenge

    • Data relevant to their session.

This is covered in more detail in Verify Endpoint Results below.

How to call the Verify Endpoint

There are two ways to call the Verify Endpoint. You can use a Get or Post request in your code to pass the private key and session token, or you can pass them on an HTTP header.

GET or POST request

Make a GET or POST request to the Verify Endpoint. In the request include:

  • Your private key

  • A session token containing the value of the response.token from the response object.

The path for the Verify Endpoint is /api/v2/verify/. The domain to use is verify-api.arkoselabs.com. So the full url would be https://verify-api.arkoselabs.com/api/v2/verify/.

Suggested code for various languages is shown below.

Private Key and Session Token HTTP headers

In the instructions above, the private key and session token are passed via the URL query parameters. An alternative method of passing the private key and session token to the verify endpoint is via HTTP headers on the request:

curl -H "Content-Type: application/json" -H "Arkose-Private-Key: <your private key>" -H "Arkose-Session-Token: <value of verification-token>" https://verify-api.arkoselabs.com/api/v2/verify/

 

Verify Endpoint Results

Verify Endpoint results can be returned in a simple binary 1 or null/empty format, or in a verbose format.

If you include simple_mode=1 parameter on your validation call, the server will return null/empty on failure and 1 on success. See the Java and .NET code samples above to see how simple-mode=1 is used.

If you do not specify simple-mode, a full JSON response will be returned with the possible values shown in the table below.

See Response Schema below for the full schema.

Field

Description

Values

solved

Whether the Enforcement Challenge was successfully solved or not

true, false

user_ip

The IP address of the user who interacted with the Enforcement Challenge

An IP address, e.g. "199.220.42.206", or null

session

A unique token for the Arkose Labs session. A session is the whole experience from solution load to verification.

A unique token, e.g. "3595d2c014d3c5f01.1116018803", or null

session_created

An ISO 8601 UTC timestamp signifying the time the session was created

e.g. "2019-07-15T02:45:13+00:00", or null

check_answer

An ISO 8601 UTC timestamp signifying the time that the Enforcement Challenge user supplied answered were evaluated

e.g. "2019-07-15T02:45:13+00:00", or null

verified

An ISO 8601 UTC timestamp signifying the time that the request to the verify endpoint was made

e.g. "2019-07-15T02:45:13+00:00"

previously_verified

Whether a user has already been verified, or not

true, false

session_timed_out

Whether a session timed out before it was solved, or not

true, false

suppress_limited

Whether the user started in lowsec session but failed verification, or not

true, false

theme_arg_invalid

Whether the theme arg at verification matched the original theme arg, or not

true, false

suppressed

Whether the user was in suppressed mode, or not

true, false

attempted

Whether the user attempted to solve the Enforcement Challenge, or not

true, false

punishable_actioned

Whether the random curse was activated, causing the user to fail on verification (regardless of the success of their attempt), or not

true, false

telltale_user

UID for a combination of telltales that identify a particular bad user or organisation

e.g. "999b-fwh", or null

session_is_legit

Whether Arkose Labs certifies there are no telltales of non-legitimate activity in the session, or not

1, 0 (signifying true, false respectively)

failed_low_sec_validation

Whether the user started a lowsec session and then failed to qualify for it when the verification was attempted, or not

true, false

lowsec_error

An identifier showing why a user was denied a lowsec session

"user_credits", "rate_limit_local", "validation_checks", "rate_limit_global", or null

lowsec_level_denied

The lowsec level that was denied to the user

A security level, e.g. 5

ip_rep_list

An identifier which specifies which ip reputation database this IP address has been seen at

"tor", "sfs_tor", "sfs", or null

security_level

A number that indicates the security level that was used for this session

A security level, e.g. 20

optional

An object containing optional return values such as client_encrypted_mode_key or get_pass values, relevant data that is being sent to Arkose Labs via our accepted methods (see: Data Exchange) will appear in this object, the keys and values inside this object will vary based on implementation

e.g.

'{ "blob": "lHpwagBqx3JOI7t9Ka0KUdIeHZbIjAYPPB72kDu2Zb5BwNiC6qJx5gS0f5c3EzcZ9d" }', or null

error

An error message describing any errors that occurred

e.g. "DENIED ACCESS", or null

Sample Verify Endpoint Responses

The following examples show different Verify Endpoint responses. They show the typical values in each field for each type of response.

Successfully Solved EC

Click here to expand...
{
    "solved": true,
    "user_ip": "203.220.42.206",
    "session": "25d2bd2b4e259e5.5188488603",
    "session_created": "2019-07-15T01:11:17+00:00",
    "check_answer": "2019-07-15T01:11:23+00:00",
    "verified": "2019-07-15T01:11:26+00:00",
    "attempted": true,
    "security_level": 20,
    "session_is_legit": 1,
    "previously_verified": false,
    "session_timed_out": false,
    "suppress_limited": false,
    "theme_arg_invalid": false,
    "suppressed": false,
    "punishable_actioned": false,
    "telltale_user": null,
    "failed_low_sec_validation": false,
    "lowsec_error": null,
    "lowsec_level_denied": null,
    "ip_rep_list": null,
    "optional": null,
    "error": null
}

Failed EC

Click here to expand...
{
    "solved": false,
    "user_ip": "203.220.42.206",
    "session": "1605d2bd30f151392.3130439903",
    "session_created": "2019-07-15T01:12:47+00:00",
    "verified": "2019-07-15T01:13:17+00:00",
    "attempted": false,
    "security_level": 50,
    "session_is_legit": 1,
    "check_answer": null,
    "previously_verified": false,
    "session_timed_out": false,
    "suppress_limited": false,
    "theme_arg_invalid": false,
    "suppressed": false,
    "punishable_actioned": false,
    "telltale_user": null,
    "failed_low_sec_validation": false,
    "lowsec_error": null,
    "lowsec_level_denied": null,
    "ip_rep_list": null,
    "optional": null,
    "error": null
}

Failed EC with an Error Message

Click here to expand...
{
    "error": "DENIED ACCESS",
    "verified": "2019-07-15T01:14:02+00:00",
    "solved": false,
    "user_ip": null,
    "session": null,
    "session_created": null,
    "check_answer": null,
    "previously_verified": false,
    "session_timed_out": false,
    "suppress_limited": false,
    "theme_arg_invalid": false,
    "suppressed": false,
    "attempted": false,
    "punishable_actioned": false,
    "telltale_user": null,
    "session_is_legit": null,
    "failed_low_sec_validation": false,
    "lowsec_error": null,
    "lowsec_level_denied": null,
    "ip_rep_list": null,
    "security_level": null,
    "optional": null
}

A Successfully Solved EC Showing lowsec_error

Click here to expand...
{
    "solved": true,
    "user_ip": "203.220.42.206",
    "session": "8975d2bd3e588b729.5002187703",
    "session_created": "2019-07-15T01:16:22+00:00",
    "check_answer": "2019-07-15T01:16:37+00:00",
    "verified": "2019-07-15T01:16:40+00:00",
    "attempted": true,
    "security_level": 50,
    "session_is_legit": 1,
    "lowsec_error": "user_credits",
    "previously_verified": false,
    "session_timed_out": false,
    "suppress_limited": false,
    "theme_arg_invalid": false,
    "suppressed": false,
    "punishable_actioned": false,
    "telltale_user": null,
    "failed_low_sec_validation": false,
    "lowsec_level_denied": null,
    "ip_rep_list": null,
    "optional": null,
    "error": null
}

A Failed EC Showing Optional Data

Click here to expand...
{
    "solved": false,
    "user_ip": "203.220.42.206",
    "session": "4815d2bd47a900da4.9266736603",
    "session_created": "2019-07-15T01:18:51+00:00",
    "verified": "2019-07-15T01:19:02+00:00",
    "attempted": false,
    "security_level": 200,
    "session_is_legit": 1,
    "optional": {
        "u_id": "u_id"
    },
    "check_answer": null,
    "previously_verified": false,
    "session_timed_out": false,
    "suppress_limited": false,
    "theme_arg_invalid": false,
    "suppressed": false,
    "punishable_actioned": false,
    "telltale_user": null,
    "failed_low_sec_validation": false,
    "lowsec_error": null,
    "lowsec_level_denied": null,
    "ip_rep_list": null,
    "error": null
}

Response Schema

This schema follows the JSON Schema standard (https://json-schema.org/). It can be used to validate the contents the response.

Click here to expand...
{
    "type": "object",
    "properties": {
        "solved": {
            "description": "Whether the EC was successfully solved or not",
            "type": "boolean",
            "default": false
        },
        "user_ip": {
            "description": "The IP address of the user who interacted with the EC",
            "type": ["string", "null"],
            "minLength": 0,
            "maxLength": 15,
            "default": null
        },
        "session": {
            "description": "A unique identifier given to a user when they create a new session",
            "type": ["string", "null"],
            "minLength": 9,
            "maxLength": 40,
            "default": null
        },
        "session_created": {
            "description": "The time the session was created",
            "type": ["string", "null"],
            "format": "date-time",
            "default": null
        },
        "check_answer": {
            "description": "The time that the EC answer check request was made",
            "type": ["string", "null"],
            "format": "date-time",
            "default": null
        },
        "verified": {
            "description": "The time that the verification request was made",
            "type": "string",
            "format": "date-time"
        },
        "previously_verified": {
            "description": "Whether a user had already been verified or not",
            "type": "boolean",
            "default": false
        },
        "session_timed_out": {
            "description": "Whether a session timed out before it could be solved",
            "type": "boolean",
            "default": false
        },
        "suppress_limited": {
            "description": "Whether the user started in a lowsec session and failed verification",
            "type": "boolean",
            "default": false
        },
        "theme_arg_invalid": {
            "description": "Whether the theme arg at verification matched the original theme arg, or not",
            "type": "boolean",
            "default": false
        },
        "suppressed": {
            "description": "Whether the user was in suppressed mode or not",
            "type": "boolean",
            "default": false
        },
        "attempted": {
            "description": "Whether the user attempted to solve the EC or not",
            "type": "boolean",
            "default": false
        },
        "punishable_actioned": {
            "description": "Whether or not the random curse was activated, causing the user to fail on verification",
            "type": "boolean",
            "default": false
        },
        "telltale_user": {
            "description": "UID for a combination of telltales that identify a particular bad user or organisation",
            "type": ["string", "null"],
            "minLength": 0,
            "maxLength": 128,
            "default": null
        },
        "session_is_legit": {
            "description": "Whether Arkose Labs certifies there are no telltales of non-legitimate activity in the session, or not",
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 1,
            "default": null
        },
        "failed_low_sec_validation": {
            "description": "Whether the user started a lowsec session and then failed to qualify for it when the verification was attempted, or not",
            "type": "boolean",
            "default": false
        },
        "lowsec_error": {
            "description": "An identifier describing an error which can occur in lowsec sessions",
            "type": ["string", "null"],
            "enum": ["user_credits", "rate_limit_local", "validation_checks", "rate_limit_global", null],
            "default": null
        },
        "lowsec_level_denied": {
            "description": "The lowsec level that was denied to the user",
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 500,
            "default": null
        },
        "ip_rep_list": {
            "description": "An identifier which specifies which ip reputation database this IP address has been seen at",
            "type": ["string", "null"],
            "enum": ["tor", "sfs_tor", "sfs", null],
            "default": null
        },
        "security_level": {
            "description": "A number that indicates the security level that was used for this session",
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 500,
            "default": null
        },
        "optional": {
            "description": "An object containing optional return values such as client_encrypted_mode_key or get_pass values",
            "type": ["object", "null"],
            "default": null
        },
        "error": {
            "description": "An error message describing any errors that occurred",
            "type": ["string", "null"],
            "default": null
        }
    },
    "required": [
        "solved",
	    "user_ip",
	    "session",
	    "session_created",
	    "check_answer",
	    "verified",
	    "previously_verified",
	    "session_timed_out",
	    "suppress_limited",
        "theme_arg_invalid",
	    "suppressed",
	    "attempted",
	    "punishable_actioned",
        "telltale_user",
        "session_is_legit",
        "failed_low_sec_validation",
        "lowsec_error",
        "lowsec_level_denied",
        "ip_rep_list",
        "security_level",
        "optional",
        "error"
    ],
    "additionalProperties": false
}

 



Was this article helpful?
0 out of 0 found this helpful