Calling Verify v4 API

πŸ“˜

Verify API Changing To Personalized URLs

As of February 2022, Arkose Labs is deprecating its previously used generic Verify API URL endpoint in favor of unique URLs personalized to our customers. If you have not already done so, please talk to your CSM about switching over to your own unique Verify URLs.

Requests to the Verify API can either be sent via:

  • An application/json body (POST)

  • A URL with query parameters (GET)

  • An HTTP header.

POST and GET Request Parameters

This table shows the parameters that should be included within the GET or POST requests.

🚧

Verify API Field Changes

From time to time, Arkose will add additional fields to the Verify API . We will not either delete fields, or change their value specification (i.e. if field "foo" has been defined as having integer values between 0 and 100, we will not change "foo" so that it has, for example, a string value or integer values between -500 and 5000).

This means you must write your Verify data processing code so it handles unknown fields and their values. For example, suppose it encounters a field "bar" and does not have a defined way of handling "bar" and its value. It could just ignore "bar" as an unknown field and go on to the next field.

SUMMARY:

Arkose will not delete any fields from the Verify API .

Arkose will not change what values a Verify API field can have.

Arkose will add additional fields and their values to the Verify API over time.

Your Verify API data processing code must be able to deal with unknown to it fields and their values in its Verify data input.

Information on the current Verify API request and response schema is in the documentation at Verify Request and Response Schemas. The source information for it is at the following URLs. Please substitute your own customized URL for the descriptions and examples used in this document.

  • Verify v4 request schema:
    <company>-verify.arkoselabs.com/api/v4/verify/schema/request

  • Verify v4 response schema:
    <company>-verify.arkoselabs.com/api/v4/verify/schema/response

e.g.
https://acme-verify.arkoselabs.com/api/v4/verify/schema/request
https://acme-verify.arkoselabs.com/api/v4/verify/schema/response

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

curl https://<company>-verify.arkoselabs.com/api/v4/verify/schema/request

The generic URLs will continue working until all customers are using their personalized URLs; e.g.

  • http://verify.arkoselabs.com/api/v4/verify/schema/request
  • http://verify.arkoselabs.com/api/v4/verify/schema/response
Parameter NameRequired / OptionalDescription
private_keyRequiredThe private key issued by Arkose Labs along with the public key used for the client-side API.
session_tokenRequiredThe token value contained within the token key of the client-side API response object. This object is provided within the client-side onComplete callback.
log_dataOptionalA freeform string that allows information to be passed to the Verify API. This can be used to pass basic information that you want stored by Arkose with the session data. This can be used internally by Arkose when performing manual traffic analysis.

GET request

Below is an example URL that includes the parameters from the above table as query parameters. Before actually using it, replace the ??? placeholders with the real values to be used, as well as replacing <company> with your company's personalized API URL name.

https://<company>-verify.arkoselabs.com/api/v4/verify/?private_key=???&session_token=???&log_data=???

POST request

The POST request requires the use of the request body. Below is an example of a JSON request body using the parameters from the table above. Note that only in POST requests can you have an optional email_address field. For information about how to send an email address and how Arkose uses it, see the Knowledge Base (support login required) here and here. Do not use the email_address field until you have read its documentation and/or spoken to your Arkose rep about it.

{
  private_key: "_PRIVATE_KEY_HERE_",
  session_token: "_SESSION_TOKEN_HERE_",
  log_data: "_LOG_DATA_HERE_",
  email_address: "_EMAIL_ADDRESS_HERE_"
}

HTTP Header Request

πŸ“˜

Requests using HTTP headers do not support log_data

In the instructions above, the private key and session token are passed via the URL query parameters (GET) or POST body. An alternative method of passing the private key and session token to the Verify API is via HTTP headers on the request. The table below shows the name of the headers that should be used.

Parameter NameRequired / OptionalDescription
Arkose-Private-KeyRequiredThis is the private key issued by Arkose Labs along with the public key used for the client-side API
Arkose-Session-TokenRequiredThis is the token value contained within the token key of the client-side API response object. This object is provided within the client-side onComplete callback

Here is an example of providing the required data using the headers listed above in a simple Curl command.

curl -H "Content-Type: application/json" -H "Arkose-Private-Key: <your private key>" -H "Arkose-Session-Token: <value of verification-token>" https://<company>-verify.arkoselabs.com/api/v4/verify/