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