Akamai Web v3 sensor data API

Akamai Web V3 is a sophisticated bot detection solution that uses a combination of client-side techniques to identify and block automated traffic. Our API takes care of the heavy lifting for you, leaving you to focus on your use case instead of worrying about bot detection.

It's often used in conjunction with Akamai Web SBSD. While SBSD is usually not mandatory, when facing problems with low success rates, we recommend trying our SBSD solution.

warning

We do not support illicit use of our API, and we will not hesitate to block any users who abuse it. We are committed to providing a safe and secure experience for all of our users, and we will take action against anyone who violates our terms of service. Unblocking may only be possible after ID KYC verification and/or valid justification.

Getting started

To confirm whether a website uses Akamai Web V3, you have to check for the presence of the _abck cookie. It's internally what governs the authenticity of the session. In order to obtain a valid _abck, you have to send POST requests to Akamai endpoint. The URL is dynamic; however you can easily obtain it by parsing the script tag at the bottom of the page:

<script type="text/javascript" src="/9I4aWp/NQ2flM/S6/tnMF/I6tE95/LuOiSGiDDO1uGQ7wNY/ZR4HPEILAQ/HzoWMgJe/YloB">

With the parsed script src attribute, you have to resolve the full URL by adding the website's domain name, and you will get the endpoint you need to send POST requests to:

https://example.com/9I4aWp/NQ2flM/S6/tnMF/I6tE95/LuOiSGiDDO1uGQ7wNY/ZR4HPEILAQ/HzoWMgJe/YloB

Good job! You have just obtained the endpoint URL needed to send POST requests and obtain a valid _abck cookie.

Flow

We provide a Golang SDK for your convenience, but you can also use our API with any programming language that supports HTTP requests. For convenience, we will use our SDK in the examples below.

info

Session management

Keep using the same SDK session for a coherent sensor sequence. The SDK owns the opaque API session state and updates it after every successful generation.

AkamaiWebV3Session returns a builder and makes no request. Create only creates local SDK state, so it does not accept a context and is not charged. The first Sensor call initializes the remote session and sends the script body.

session := verisClient.AkamaiWebV3Session(
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36",
    scriptURL,
    scriptBody,
    "en-US,en;q=0.9",
).Create()

The user agent and language must match the target requests. language accepts either a plain BCP-47 tag (en-US) or the full Accept-Language header value captured from the target browser (en-US,en;q=0.9). To align generated geolocation data with a proxy, call WithIP(proxyExitIP) before Create.

Let's revisit key detection flags

Header order
accept-language header value
Proxy country
TLS fingerprint

If any of those are unfamiliar to you, please visit Getting started for more information.

1. `GET` initial page

Start with a normal request to the page you want to access. Parse the Akamai script tag from the response and resolve it into a full URL.

2. `GET` Akamai V3 Script

Request the script URL you extracted in the previous step. This gives you the script body required to initialize the session.

3. Obtain payload

After you have created a session, you can obtain a payload by calling the Sensor method on the session object:

sensor, _, err := session.Sensor(ctx, pageURL, abck, bmSz)

pageURL is the current browser location (window.location.href)
abck and bmSz are the current values of the _abck and bm_sz cookies from your cookie jar.

Each Sensor call makes one charged API request. The script body is required to be sent only on the first call.

4. Send `POST` request and retry until session is valid

Send the payload back to the same Akamai endpoint. Repeat the process until the session looks valid, then make your protected request.

Complete example (SDK)

Imports and HTTP helpers are omitted for brevity. Assume getInitialPage, getV3Script, postV3Payload, postProtectedEndpoint, extractScriptSrc, and getCookie all reuse the same configured client, cookie jar, proxy, headers, and TLS fingerprint. This example assumes the target uses ~0~ in _abck as its stop signal.

func runFlow(ctx context.Context, verisClient *veris.Client) error {
	const (
		userAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36"
	)

	homeBody, err := getInitialPage(ctx, "https://example.com/home")
	if err != nil {
		return err
	}

	scriptURL, ok := veris.ExtractAkamaiWebV3ScriptURL("https://example.com", homeBody)
	if !ok {
		return fmt.Errorf("failed to extract Akamai V3 script URL")
	}

	scriptBody, err := getV3Script(ctx, scriptURL)
	if err != nil {
		return err
	}

	session := verisClient.AkamaiWebV3Session(
		userAgent,
		scriptURL,
		scriptBody,
		"en-US,en;q=0.9",
	).Create()

	valid := false
	for attempt := 0; attempt < 8; attempt++ {
		payload, _, err := session.Sensor(
			ctx,
			homeURL,
			getCookie("_abck"),
			getCookie("bm_sz"),
		)
		if err != nil {
			return err
		}

		if err := postV3Payload(ctx, scriptURL, payload); err != nil {
			return err
		}

		if strings.Contains(getCookie("_abck"), "~0~") {
			valid = true
			break
		}
	}

	if !valid {
		return fmt.Errorf("Akamai V3 session did not become valid")
	}

	resp, err := postProtectedEndpoint(ctx, "https://example.com/api/protected")
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	if resp.StatusCode == http.StatusForbidden {
		return fmt.Errorf("blocked after sensor flow")
	}

	return nil
}

When to stop?

Some websites use a stop signal (~0~) in _abck cookie value, which indicates that the session is valid and you can stop sending POST requests. If website uses this signal and you don't get it after 8 attempts, it's likely that something got fingerprinted. Sending more requests is unlikely to help.
If website doesn't use stop signal, please send exactly 4 POST requests and do a request to protected resource. If you get 403, it's likely that something got fingerprinted.

Getting started​

Flow​

Session management​

Let's revisit key detection flags​

1. GET initial page​

2. GET Akamai V3 Script​

3. Obtain payload​

4. Send POST request and retry until session is valid​

Complete example (SDK)​

When to stop?​