Server-Side Instructions

Overview

There are two steps required to fully implement the Arkose Labs Detection and Prevention Platform (Arkose Labs Platform):
  1. Client-side implementation that allows the Arkose Labs Platform to collect data necessary to classify the traffic from the client, display an Enforcement Challenge (EC) if necessary, and provide a one-time use token.

  2. Server-side implementation that takes the token provided by the client-side and verifies it with the Arkose Labs verify API. The result is a response that contains information about the session, either in a simple format or as a JSON.

This guide documents the steps required to implement the server-side verification.

Detailed information on implementing the Arkose Labs Platform client-side API can be found in the Standard Setup guide.

API Request Authentication

Arkose Labs authenticates your API requests using a private/public key pair that can be retrieved from the Site Settings page of the Arkose Labs Client Dashboard. If you do not have access to the dashboard or do not have your private and public keys, contact your Sales Rep or Sales Engineer.

The private key is needed to authenticate when using the verify API. This private key must not be published on a client facing website, and must only be used on your server-side implementation on the Arkose Labs verify API.

Verify API Request and Response Schemas

Information on the current verify API request and response schema can be found at:

Request schema:

http://verify-api.arkoselabs.com/api/v3/verify/schema/request

Response schema:

http://verify-api.arkoselabs.com/api/v3/verify/schema/response

Here is an example of how to get the response schema using cURL:

curl https://verify-api.arkoselabs.com/api/v3/verify/schema/request

Calling the Verify API

To call the verify API, make a POST request to the following URL:

https://verify-api.arkoselabs.com/api/v3/verify/

Include the data shown below in the body of the request, as defined in the API request schema:

  • Your private key - required

  • A session token containing the value of response.token from the client-side API - required

  • Log data containing free form string data - optional

This data must be passed as a JSON object, for example:

{
  "private_key": "<your private key>",
  "session_token": "<value of verification-token>"
  "log_data": "<string of data to be sent - OPTIONAL>"
}
curl -X POST -H "Content-Type: application/json" -d '{"private_key":"<your private key>", "session_token":"<value of verification-token>"}' https://verify-api.arkoselabs.com/api/v3/verify/

Response Types

There are two types of response from the verify API:

  • A binary response that contains only 1 or null/empty

  • A full JSON object that contains data relevant to the session being verified

The response type is controlled through the inclusion of a query parameter in the API URL:

  • simple_mode = 0 will return the full JSON response. This is the default if no query parameter is provided.

  • simple_mode = 1 will return the binary response (1/0)

For example, if a binary response is required then the following cURL example would be used:

curl -X POST -H "Content-Type: application/json" -d '{"private_key":"<your private key>", "session_token":"<value of verification-token"}' https://verify-api.arkoselabs.com/api/v3/verify/?simple_mode=1

Processing the Verify API Response

The reason for performing the verification step is to ensure that the user cannot proceed with their action unless their session is valid. Each response.token provided by the client-side API can only be used once. This means that a solved session token cannot be reused to bypass Arkose challenges.

Once a response.token has been verified using the verify API, it cannot be used again.

Check the API response. Allow the user to continue only if:

  • For a simple Response

    • The returned value is 1

  • For a JSON Response

    • The value of the solved key within the response is true.

Any other value means that the user’s response was not valid.

Verify API JSON Response Details

See Response Schema for the full schema.

The only key value necessary for making a decision on allowing a user action to continue is solved. All other values are for informational purposes only.

Field

Description

Values

solved

Whether the Enforcement Challenge was successfully solved or not

true, false.

Sessions should only be allowed to continue if the value of this field is TRUE

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 session 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 session qualified for low security, but failed verification, or not. Low security is when a session has qualified to run in transparent mode, or use an enforcement challenge that has no wrong answer e.g. a ‘pick your favourite color’ challenge

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.

Be aware that security_level can have a null value - usually because the session was an audio mode session. Audio mode does not use security_level.

A security level, e.g. 20
Null, if the session was an audio mode session.

ua

The User Agent string for the user that interacted with the EC

e.g.

“Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.129 Safari/537.36”

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 API 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,
    "ua": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/81.0.4044.129 Safari\/537.36"
    "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,
    "ua": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/81.0.4044.129 Safari\/537.36"
    "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,
    "ua": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/81.0.4044.129 Safari\/537.36"
    "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,
    "ua": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/81.0.4044.129 Safari\/537.36"
    "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,
    "ua": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/81.0.4044.129 Safari\/537.36"
    "error": null
}

Request Schema

The request and response schemas follow the JSON Schema standard. For more information about the JSON Schema standard see https://json-schema.org/.

Click here to expand...
{
    "type": "object",
    "properties": {
        "private_key": {
            "description": "The private key associated with EC that served this session",
            "type": "string"
        },
        "session_token": {
            "description": "The session token which identifies the session to verify",
            "type": "string"
        },
        "log_data": {
            "description": "A field to allow a free form piece of string data",
            "type": "string"
        }
    },
    "required": [
        "private_key",
        "session_token"
    ]
}

Response Schema

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"],
            "format": "ipv4",
            "default": null
        },
        "session": {
            "description": "A unique identifier given to a user when they create a new session",
            "type": ["string", "null"],
            "pattern": "^[0-9A-Fa-f]+\\.[0-9]{10}$",
            "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",
            "minimum": 0,
            "maximum": 1,
            "default": 0
        },
        "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",
            "minimum": 0,
            "maximum": 500,
            "default": 0
        },
        "ua": {
            "description": "The User Agent string for the user that interacted with the EC",
            "type": ["string", "null"],
            "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 occured",
            "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",
        "ua",
        "optional",
        "error"
    ]
}

 

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