Overview

This document outlines how to make POST requests to the Arkose Labs Edge API, including endpoint structure, required headers, and request body format.

API Access Methods

Edge API can be accessed via a direct HTTP request.

Request URL format:

https://client-api.arkoselabs.com/api/edge/v1/<public_key>

Example using curl:

curl https://client-api.arkoselabs.com/api/edge/v1/<public_key> \
    -H "Content-Type: application/json" \
    -d '{"private_key": "<private_key>", "ip_address": "1.2.3.4","workflow": "login"}'

Request Body Parameters

Note: Though only private_key and ip_addressare required fields, sending the other fields (such as OS, platform, JA3/JA4 fingerprints, TLS details, and full headers) is strongly recommended, as they significantly improve our detection accuracy and reduce false positives.

Fields	Sub-Fields	Type	Required	Description
`private_key`		string	Yes	The private key issued by Arkose Labs along with the public key used for the client-side API.
`ip_address`		string	Yes	IP address of the client making the request.
`workflow`		string	No	Indicates in which user flow the Edge API is integrated (e.g., login, payment). This field only accepts alphabetic characters; spaces, numbers and special characters are NOT allowed
`os`		string	No	Operating system name (e.g., "OS X", "Windows").
`os_version`		string	No	Version of the OS (e.g., "10.15").
`platform`		string	No	Platform (e.g., "MacIntel", "Win32").
`ja3`		string	No	JA3 fingerprint of the TLS Client Hello.
`ja4`		string	No	JA4 fingerprint (includes more TLS details).
`email_address`		string	No	Email address from the request, if applicable.
`headers`		object	No	HTTP headers from the client request (key-value pairs).
	`headers.additionalProperties`	string	No	Additional properties for headers.
`request`		object	No	Request details.
	`request.method`	string	No	HTTP method used by the client (e.g., GET, POST).
	`request.url`	string	No	Originating/Use case URL.
`tls`		object	No	TLS details.
	`tls.cipher`	string	No	TLS cipher suite used (e.g., "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384").
	`tls.protocol`	string	No	TLS protocol version (e.g., "TLSv1.3").

Request Schema with Example

The POST request should include a JSON body structure as shown below:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "The edge-api request body schema",
  "type": "object",
  "properties": {
    "private_key": {
      "type": "string"
    },
    "ip_address": {
      "type": "string"
    },
    "workflow": {
      "type": "string"
    },
    "os": {
      "type": "string"
    },
    "os_version": {
      "type": "string"
    },
    "platform": {
      "type": "string"
    },
    "ja3": {
      "type": "string"
    },
    "ja4": {
      "type": "string"
    },
    "email_address": {
      "type": "string"
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "request": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string"
        },
        "url": {
          "type": "string"
        }
      }
    },
    "tls": {
      "type": "object",
      "properties": {
        "cipher": {
          "type": "string"
        },
        "protocol": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "private_key",
    "ip_address",
		"workflow"
  ]
}

{
  "private_key": "B4DFA9BC-XXXX-XXXX-XXXX-D24DD4C8C27D",
  "ip_address": "11.22.33.44",
  "os": "OS X",
  "os_version": "10.15",
  "platform": "MacIntel",
  "ja3": "e7d705a3286e19ea42f587b344ee6865",
  "ja4": "t13d1516h2_8daaf6152771a5b3",
  "email_address": "[email protected]",
  "workflow": "login",
  "headers": {
    "Accept": "*/*",
    "Accept-Language": "en-GB,en-US;q=0.9,en;q=0.8",
    "cache-control": "no-cache",
    "content-type": "application/x-www-form-urlencoded; charset=UTF-8",
    "Cookie": "sessionid=abc123; user_preference=something; visitcount=42; auth_token=xyzsometoken",
    "Origin": "https://test-cases.arkoselabs.com",
    "pragma": "no-cache",
    "priority": "u=1, i",
    "Referer": "https://test-cases.arkoselabs.com/",
    "Sec-Ch-Ua": "\"Chromium\";v=\"128\", \"Not;A=Brand\";v=\"24\", \"Google Chrome\";v=\"128\"",
    "SEC-CH-UA-MOBILE": "?0",
    "sec-ch-ua-platform": "\"macOS\"",
    "sec-fetch-dest": "empty",
    "sec-fetch-mode": "cors",
    "sec-fetch-site": "cross-site",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
  },
  "request": {
    "method": "POST",
    "url": "https://sample-website.com/sample-path"
  },
  "tls": {
    "cipher": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
    "protocol": "TLSv1.3"
  }
}