Overview

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 https://arkoselabs.atlassian.net/wiki/spaces/DG/pages/214176229 guide.

API Sequence

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:

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

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

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/

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:

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

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

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

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. For more information about the JSON Schema standard see 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" ] }