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

Get Verify Endpoint Schemas

Use the schema endpoints below to get the latest versions of the Verify endpoint JSON schema:

Use the verify-api.arkoselabs.com domain.

For the request schema add:

api/v3/verify/schema/request

For the response schema add:

api/v3/verify/schema/response

Here is an example accessing the request schema endpoint, using Curl:

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

Use the Verify Endpoint

Make a 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.

  • Log data containing a free form piece of string data. This field is optional.

The endpoint for verification is:

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

The data must be passed in the request’s body data as a JSON object:

1 2 3 4 5 6 { "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/

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. For example:

1 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

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

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.

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 { "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 (https://json-schema.org/).

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 { "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" ] }