Verify Endpoint v1.0

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

 

The Verify Endpoint is used to verify Arkose Labs Fraud and Abuse Prevention Platform (Arkose Labs Platform) enforcement challenge (EC) responses from users. 

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

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 full url for the Verify Endpoint is https://verify-api.arkoselabs.com/fc/v/

Suggested code for various languages is shown below:


Verify Endpoint Code
 
PHP: 

In PHP when you are passing the response to the server-side, you must pass:

  • Your private key. In the example below, replace “_PRIVATE_KEY_HERE_” with your private key

  • The value of the response.token passed back in the response object. In the example below, the response.token is in “fc-token”

This information must be passed to the Verify Endpoint server via POST or GET.


$private_key =
"_PRIVATE_KEY_HERE_";
$session_token = $_POST["fc-token"];
$fc_api_url = "https://verify-api.arkoselabs.com/fc/v/?private_key=".$private_key."&session_token=".$session_token;
$fc_results = json_decode(file_get_contents($fc_api_url)); //the api returns a JSON result
if (isset($fc_results->solved) && $fc_results->solved == true) {
    //valid, the user has solved correctly
} else {
    //invalid, the user has failed the test and should be prompted to try it again
}
 
Java:

In your Java code when you are passing the response to the server-side, you must pass:

  • Your private key. In the example below, replace “_YOUR_PRIVATE_KEY_” with your private key

  • The value of the response.token passed back in the response object on the client-side. In the example below, the response.token is in “fc-token”

This information must be passed to the Verify Endpoint server via POST or GET.

String private_key = "_YOUR_PRIVATE_KEY_";
URL url = new URL("https://verify-api.arkoselabs.com/fc/v/?private_key="+private_key+"&session_token="+request.getParameter("fc-token")+"&simple_mode=1");
BufferedReader reader = new BufferedReader(new InputStreamReader(url.openStream(), "UTF-8"));
String result = reader.readLine();
if (result.equals("1")) {
    //valid, the user has solved the EC correctly
} else {
    //invalid, the user has failed EC
}

You will need to import the following Java libraries for the above example:

Comments in the sample code show where you must handle a valid or invalid response from the validation on the EC.

 

.NET

In your .Net code where you are validating your form (most likely within your controller), you must pass the following values to the server-side:

  • Your private key. In the example below, replace “_YOUR_PRIVATE_KEY_” with your private key

  • The value of the response.token passed back in the response object. In the example below, the response.token is in “fc-token”

This information must be passed to the Verify Endpoint server via POST or GET.

const string privateKey = "_YOUR_PRIVATE_KEY_";
string sessionToken = Request.Form["fc-token"];
string url = string.Format("https://verify-api.arkoselabs.com/fc/v/?private_key={0}&session_token={1}&simple_mode=1", privateKey, sessionToken);
if (new WebClient().DownloadString(url) == "1") {
    //valid, the user has solved EC correctly
} else {
    //invalid, the user has failed EC
}

Comments in the sample code show where you must handle a valid or invalid response from the validation on the EC.

 

Ruby:

In your Ruby code when you are passing the response to the server-side, you must pass:

  • Your private key. In the example below, replace “_YOUR_PRIVATE_KEY_” with your private key

  • The value of the response.token passed back in the response object on the client-side. In the example below, replace “_SESSION_TOKEN_HERE_” with the response.token.

require 'open-uri'
require 'json'
private_key = "_PRIVATE_KEY_HERE_"
session_token = "_SESSION_TOKEN_HERE_"
fc_api_url = "https://verify-api.arkoselabs.com/fc/v/?private_key=#{private_key}&session_token=#{session_token}"
buffer = open(fc_api_url).read
fc_results = JSON.parse(buffer)
if fc_results["solved"] && fc_results["solved"] == true
# valid, the user has solved correctly
else
# invalid, the user has failed the test and should be prompted to try it again
end

 

Other:

In your server-side code, when you are calling the Verify Endpoint, you must pass:

  • Your private key. In the example below, replace _YOUR_PRIVATE_KEY with your private key

  • The value of the response.token passed back in the response object. In the example below, the response.token is in _VALUE_OF_fc-token_

This information must be passed to the Verify Endpoint server via a GET request.

https://verify-api.arkoselabs.com/fc/v/?private_key=_YOUR_PRIVATE_KEY&session_token=_VALUE_OF_fc-token_

 

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.

Key Example Value Optional Description
solved TRUE/FALSE No Whether the Enforcement Challenge was successfully solved or not
score 0 No Always 0 for now. May be used in future.
user_ip 163.207.150.119 No The IP address of the user who interacted with the Enforcement Challenge

 

OTHER These values are additional information and are always returned in Other.
session 957585b3a141993c8.64352581 No A unique token for the Arkose Labs session. A session is the whole experience from solution load to verification.
time_verified 1482373662 No Unix timestamp of when the verify request to the Verify Endpoint was made
attempted FALSE Yes

Whether the user attempted to solve the EC or not. The value is FALSE if the user didn't interact with an EC but it was submitted for verification. For example, if the user hit submit on the EC form without solving the EC first.
This field will not be returned when the value is TRUE. This may be detected as a NULL value.

previously_verified TRUE Yes TRUE if this session has previously been validated. Sessions can only be validated once. This prevents replay attacks.
session_timed_out TRUE Yes TRUE if session failed verification because the session is too old. Sessions can only live for a certain time, by default 30 minutes. 
suppressed TRUE Yes TRUE if an EC was not shown due to user's designation by the Arkose Labs system as safe to pass through.
suppress_limited TRUE Yes TRUE if ordinarily an EC would not be shown, but the user exceeded a rate limit so the EC was shown. See 
session_created 2017-10-24T22:44:17+00:00 Yes The time when the Arkose Labs API call started the process of producing a session.
check_answer 2017-10-24T22:44:24+00:00 Yes The time when the user last submitted an answer to an EC. This is null if no EC was shown or no answer was provided.
verified 2017-10-24T22:44:26+00:00 Yes The time when the Arkose Labs server verified the session.

 

DENIED ACCESS Failure Conditions

In rare cases, the verify call may respond with a HTTP 200 {"error":"DENIED ACCESS"}

The following are conditions that may lead to this error:

  • invalid session data
  • missing region
  • missing private key
  • incorrect private key length
  • invalid private key
  • missing session token
  • missing public key - public key does not exist in the database
  • could not find session - unable to find the session anywhere
  • public key missing cache
  • public key mismatch cache - corrupt data
  • public key not set for anonymous mode encryption
  • invalid secure mode decryption
  • not encryption mode.
Was this article helpful?
0 out of 0 found this helpful