Solve your first Akamai challenge

What you will build. A small script that loads a protected page the way a browser does, asks Roolink for the sensor the page expects, posts it back, and ends with a cookie the site trusts. That cookie is what lets your next request through.

What you need. A Roolink account with an API key, a residential proxy that keeps the same IP for a session, powhttp installed, and Python, Go or Node. Pick your language in any code block; every block on the page follows.

1Set up

Copy your API key from the dashboard and put it in an environment variable, along with your proxy URL. Then install two packages: the Roolink SDK, which talks only to Roolink, and a TLS client, which talks to the target site.

Open powhttp, start recording, and load your target page in Chrome. Keep that recording open. Every request you make below has a matching one in it, and you will copy the headers from there.

The TLS client is not optional. Akamai fingerprints the connection and the exact order of your headers before the sensor matters. The libraries below are the ones we recommend; Set up your HTTP client explains each setting.

export ROOLINK_API_KEY="roo_..."
export PROXY_URL="http://user:pass@host:port"

pip install roolink git+https://github.com/Nintendocustom/Python-Tls-Client.git

export ROOLINK_API_KEY="roo_..."
export PROXY_URL="http://user:pass@host:port"

go get github.com/roolinkio/roolink-go
go get github.com/bogdanfinn/tls-client

export ROOLINK_API_KEY="roo_..."
export PROXY_URL="http://user:pass@host:port"

npm install @roolink/sdk tlsclientwrapper

2Load the page and find the script

Start the way a person would: open the page that comes before the protected action. For a shop, that is the product page before add to cart. Send it through your proxy with the headers Chrome sent for that page in your powhttp recording, in the same order.

Two things come back. The response sets the _abck and bm_sz cookies, and the HTML contains one <script> tag whose path looks random, near the end of the body. That path is different for every site and changes over time, so read it from the page each run.

You should see a 200 and a script path such as /aB3dE/fG7/hI/jK/LmNoPqRsTuVwXyZ.

import json, os, re
import tls_client
from roolink import RoolinkClient, WebSensorRequest

PAGE = "https://www.example.com/product/123"
ORIGIN = "https://www.example.com"
UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36"

roolink = RoolinkClient(os.environ["ROOLINK_API_KEY"])
site = tls_client.Session(client_identifier="chrome_152", random_tls_extension_order=True)
site.proxies = {"http": os.environ["PROXY_URL"]}

page = send("GET", PAGE, PAGE_HEADERS)
script_path = re.search(r'<script[^>]+src="(/[^"]+)"[^>]*defer', page.text).group(1)
script_url = ORIGIN + script_path
print(page.status_code, script_path)

const (
	page   = "https://www.example.com/product/123"
	origin = "https://www.example.com"
	ua     = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36"
)

rl := roolink.NewClient(os.Getenv("ROOLINK_API_KEY"))

jar := tls_client.NewCookieJar()
site, err := tls_client.NewHttpClient(tls_client.NewNoopLogger(),
	tls_client.WithClientProfile(profiles.Chrome_152),
	tls_client.WithRandomTLSExtensionOrder(),
	tls_client.WithCookieJar(jar),
	tls_client.WithProxyUrl(os.Getenv("PROXY_URL")),
)
if err != nil {
	log.Fatal(err)
}

html := get(site, page, pageHeaders(""))
scriptPath := regexp.MustCompile(`<script[^>]+src="(/[^"]+)"[^>]*defer`).FindStringSubmatch(html)[1]
scriptURL := origin + scriptPath
fmt.Println(scriptPath)

import { ModuleClient, SessionClient } from "tlsclientwrapper";
import { RoolinkClient } from "@roolink/sdk";

const PAGE = "https://www.example.com/product/123";
const ORIGIN = "https://www.example.com";
const UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36";

const roolink = new RoolinkClient(process.env.ROOLINK_API_KEY!);
const moduleClient = new ModuleClient();
const site = new SessionClient(moduleClient, {
  tlsClientIdentifier: "chrome_146",
  withRandomTLSExtensionOrder: true,
  proxyUrl: process.env.PROXY_URL,
});

const page = await send("GET", PAGE, pageHeaders());
const scriptPath = page.body.match(/<script[^>]+src="(\/[^"]+)"[^>]*defer/)![1];
const scriptUrl = ORIGIN + scriptPath;
console.log(page.status, scriptPath);

3Fetch and parse the script

Download the script through the same session, using the headers from the script request in your recording. Then hand its body to Roolink’s /parse endpoint. Roolink reads the site’s configuration out of the script and returns a small object, called the script data, that every sensor for this site needs.

The result stays valid until the site changes its script, so cache it and reuse it across sessions.

You should see an object with ver, key, dvc and din fields.

script = send("GET", script_url, SCRIPT_HEADERS)
script_data = roolink.parse_script(script.text)
print(script_data["ver"])

scriptBody := get(site, scriptURL, scriptHeaders())
scriptData, err := rl.ParseScript(context.Background(), []byte(scriptBody))
if err != nil {
	log.Fatal(err)
}
fmt.Println(scriptData.Ver)

const script = await send("GET", scriptUrl, scriptHeaders());
const scriptData = await roolink.parseScript(script.body);
console.log(scriptData.ver);

4Generate the sensor and post it

Now ask Roolink for the sensor. Send the page URL, the same User-Agent your session uses, the current _abck and bm_sz cookies, the script URL and the script data. Set stepper to true and pass the attempt number as index, starting at 0: that way each sensor continues the same visitor’s timeline instead of starting a new one. Roolink returns one long string.

Post that string to the script path on the site, wrapped as {"sensor_data": "..."} with a text/plain content type. The site replies {"success": true} and sends back an upgraded _abck cookie.

Check the cookie. If it contains ~0~, you are through. If it still contains ~-1~, generate and post another sensor with the new cookie values. Three posts is the ceiling: if the cookie has not flipped by then, the problem is the connection, not the sensor. Start with Troubleshoot a block.

You should see {"success": true} from the site and a _abck value containing ~0~.

for attempt in range(3):
    resp = roolink.generate_web_sensor(WebSensorRequest(
        url=PAGE,
        user_agent=UA,
        abck=site.cookies.get("_abck", ""),
        bm_sz=site.cookies.get("bm_sz", ""),
        script_url=script_url,
        script_data=script_data,
        language="en-US",
        stepper=True,
        index=attempt,
    ))
    posted = send("POST", script_url, SENSOR_HEADERS, json.dumps({"sensor_data": resp.sensor}))
    print(attempt + 1, posted.text)
    if "~0~" in site.cookies.get("_abck", ""):
        break

for attempt := 1; attempt <= 3; attempt++ {
	resp, err := rl.GenerateWebSensor(context.Background(), roolink.WebSensorRequest{
		URL:        page,
		UserAgent:  ua,
		Abck:       cookie(jar, page, "_abck"),
		BmSz:       cookie(jar, page, "bm_sz"),
		ScriptURL:  scriptURL,
		ScriptData: scriptData,
		Language:   "en-US",
		Stepper:    true,
		Index:      attempt - 1,
	})
	if err != nil {
		log.Fatal(err)
	}
	body, _ := json.Marshal(map[string]string{"sensor_data": resp.Sensor})
	fmt.Println(attempt, post(site, scriptURL, sensorHeaders(), string(body)))
	if strings.Contains(cookie(jar, page, "_abck"), "~0~") {
		break
	}
}

for (let attempt = 0; attempt < 3; attempt++) {
  const { sensor } = await roolink.generateWebSensor({
    url: PAGE,
    userAgent: UA,
    _abck: await cookie("_abck"),
    bm_sz: await cookie("bm_sz"),
    scriptUrl,
    scriptData,
    language: "en-US",
    stepper: true,
    index: attempt,
  });
  const posted = await send("POST", scriptUrl, sensorHeaders(), JSON.stringify({ sensor_data: sensor }));
  console.log(attempt + 1, posted.body);
  if ((await cookie("_abck")).includes("~0~")) break;
}

5Make the protected request

Use the same session for the request you came for. Nothing changes except that the site now trusts your _abck cookie.

Most sites invalidate the cookie after a protected action, so repeat step 4 before the next one. The script data from step 3 does not need to be fetched again.

You should see a 200. That is your first solved challenge.

cart = send("POST", ORIGIN + "/cart/add", PAGE_HEADERS, json.dumps({"sku": "123"}))
print(cart.status_code)

fmt.Println(post(site, origin+"/cart/add", pageHeaders(page), `{"sku":"123"}`))

const cart = await send("POST", ORIGIN + "/cart/add", pageHeaders(), JSON.stringify({ sku: "123" }));
console.log(cart.status);

await site.destroySession();
await moduleClient.terminate();

The complete file

The whole program in one file. The three header sets are left for you to fill from your powhttp recording: one for the page, one for the script, one for the sensor post. Copy each list in the order powhttp shows it. Header order matters as much as the values, and it is the one thing this guide will not give you, because your capture is always more current than any list here.

import json, os, re
import tls_client
from roolink import RoolinkClient, WebSensorRequest

PAGE = "https://www.example.com/product/123"
ORIGIN = "https://www.example.com"
UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36"

# Paste each header list from your powhttp recording, in the order shown there.
# Use the same User-Agent as UA above, and PAGE / ORIGIN for referer and origin.
PAGE_HEADERS = {
    # headers Chrome sent when loading the page
}

SCRIPT_HEADERS = {
    # headers Chrome sent when loading the Akamai script
}

SENSOR_HEADERS = {
    # headers Chrome sent when posting the sensor; content-type is text/plain;charset=UTF-8
}

roolink = RoolinkClient(os.environ["ROOLINK_API_KEY"])
site = tls_client.Session(client_identifier="chrome_152", random_tls_extension_order=True)
site.proxies = {"http": os.environ["PROXY_URL"]}


def send(method, url, headers, data=None):
    """Send headers in exactly the order they are written."""
    site.header_order = list(headers)
    if method == "GET":
        return site.get(url, headers=headers)
    return site.post(url, headers=headers, data=data)


def main():
    # 2. Load the page and find the script
    page = send("GET", PAGE, PAGE_HEADERS)
    script_path = re.search(r'<script[^>]+src="(/[^"]+)"[^>]*defer', page.text).group(1)
    script_url = ORIGIN + script_path

    # 3. Fetch and parse the script
    script = send("GET", script_url, SCRIPT_HEADERS)
    script_data = roolink.parse_script(script.text)

    # 4. Generate the sensor and post it, up to three times
    for attempt in range(3):
        resp = roolink.generate_web_sensor(WebSensorRequest(
            url=PAGE,
            user_agent=UA,
            abck=site.cookies.get("_abck", ""),
            bm_sz=site.cookies.get("bm_sz", ""),
            script_url=script_url,
            script_data=script_data,
            language="en-US",
            stepper=True,
            index=attempt,
        ))
        send("POST", script_url, SENSOR_HEADERS, json.dumps({"sensor_data": resp.sensor}))
        if "~0~" in site.cookies.get("_abck", ""):
            break

    # 5. Make the protected request
    cart = send("POST", ORIGIN + "/cart/add", PAGE_HEADERS, json.dumps({"sku": "123"}))
    print(cart.status_code)
    site.close()


main()

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/url"
	"os"
	"regexp"
	"strings"

	http "github.com/bogdanfinn/fhttp"
	tls_client "github.com/bogdanfinn/tls-client"
	"github.com/bogdanfinn/tls-client/profiles"
	roolink "github.com/roolinkio/roolink-go"
)

const (
	page   = "https://www.example.com/product/123"
	origin = "https://www.example.com"
	ua     = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36"
)

// Paste each header list from your powhttp recording, in the order shown there,
// and repeat that order in http.HeaderOrderKey. Use ua for user-agent and
// page / origin for referer and origin.
func pageHeaders(referer string) http.Header {
	h := http.Header{
		// headers Chrome sent when loading the page
		http.HeaderOrderKey: {},
	}
	if referer != "" {
		h.Set("referer", referer)
		h.Set("sec-fetch-site", "same-origin")
	}
	return h
}

func scriptHeaders() http.Header {
	return http.Header{
		// headers Chrome sent when loading the Akamai script
		http.HeaderOrderKey: {},
	}
}

func sensorHeaders() http.Header {
	return http.Header{
		// headers Chrome sent when posting the sensor; content-type is text/plain;charset=UTF-8
		http.HeaderOrderKey: {},
	}
}

func get(c tls_client.HttpClient, u string, h http.Header) string {
	req, _ := http.NewRequest(http.MethodGet, u, nil)
	req.Header = h
	return do(c, req)
}

func post(c tls_client.HttpClient, u string, h http.Header, body string) string {
	req, _ := http.NewRequest(http.MethodPost, u, strings.NewReader(body))
	req.Header = h
	return do(c, req)
}

func do(c tls_client.HttpClient, req *http.Request) string {
	resp, err := c.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	b, _ := io.ReadAll(resp.Body)
	fmt.Println(req.Method, req.URL.Path, resp.StatusCode)
	return string(b)
}

func cookie(jar http.CookieJar, rawURL, name string) string {
	u, _ := url.Parse(rawURL)
	for _, c := range jar.Cookies(u) {
		if c.Name == name {
			return c.Value
		}
	}
	return ""
}

func main() {
	rl := roolink.NewClient(os.Getenv("ROOLINK_API_KEY"))

	jar := tls_client.NewCookieJar()
	site, err := tls_client.NewHttpClient(tls_client.NewNoopLogger(),
		tls_client.WithClientProfile(profiles.Chrome_152),
		tls_client.WithRandomTLSExtensionOrder(),
		tls_client.WithCookieJar(jar),
		tls_client.WithProxyUrl(os.Getenv("PROXY_URL")),
	)
	if err != nil {
		log.Fatal(err)
	}

	// 2. Load the page and find the script
	html := get(site, page, pageHeaders(""))
	scriptPath := regexp.MustCompile(`<script[^>]+src="(/[^"]+)"[^>]*defer`).FindStringSubmatch(html)[1]
	scriptURL := origin + scriptPath

	// 3. Fetch and parse the script
	scriptBody := get(site, scriptURL, scriptHeaders())
	scriptData, err := rl.ParseScript(context.Background(), []byte(scriptBody))
	if err != nil {
		log.Fatal(err)
	}

	// 4. Generate the sensor and post it, up to three times
	for attempt := 1; attempt <= 3; attempt++ {
		resp, err := rl.GenerateWebSensor(context.Background(), roolink.WebSensorRequest{
			URL:        page,
			UserAgent:  ua,
			Abck:       cookie(jar, page, "_abck"),
			BmSz:       cookie(jar, page, "bm_sz"),
			ScriptURL:  scriptURL,
			ScriptData: scriptData,
			Language:   "en-US",
			Stepper:    true,
			Index:      attempt - 1,
		})
		if err != nil {
			log.Fatal(err)
		}
		body, _ := json.Marshal(map[string]string{"sensor_data": resp.Sensor})
		post(site, scriptURL, sensorHeaders(), string(body))
		if strings.Contains(cookie(jar, page, "_abck"), "~0~") {
			break
		}
	}

	// 5. Make the protected request
	post(site, origin+"/cart/add", pageHeaders(page), `{"sku":"123"}`)
}

import { ModuleClient, SessionClient } from "tlsclientwrapper";
import { RoolinkClient } from "@roolink/sdk";

const PAGE = "https://www.example.com/product/123";
const ORIGIN = "https://www.example.com";
const UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36";

// Paste each header list from your powhttp recording, in the order shown there.
// Use UA for user-agent and PAGE / ORIGIN for referer and origin.
const pageHeaders = () => ({
  // headers Chrome sent when loading the page
});

const scriptHeaders = () => ({
  // headers Chrome sent when loading the Akamai script
});

const sensorHeaders = () => ({
  // headers Chrome sent when posting the sensor; content-type is text/plain;charset=UTF-8
});

const roolink = new RoolinkClient(process.env.ROOLINK_API_KEY!);
const moduleClient = new ModuleClient();
const site = new SessionClient(moduleClient, {
  tlsClientIdentifier: "chrome_146",
  withRandomTLSExtensionOrder: true,
  proxyUrl: process.env.PROXY_URL,
});

// Send headers in exactly the order they are written.
async function send(method: "GET" | "POST", url: string, headers: Record<string, string>, body?: string) {
  const options = { headers, headerOrder: Object.keys(headers) };
  return method === "GET" ? site.get(url, options) : site.post(url, body ?? null, options);
}

// Read one cookie from the session's jar for the page's domain.
async function cookie(name: string): Promise<string> {
  const res = await site.getCookiesFromSession(site.getSession(), PAGE);
  return res.cookies?.find((c) => c.name === name)?.value ?? "";
}

// 2. Load the page and find the script
const page = await send("GET", PAGE, pageHeaders());
const scriptPath = page.body.match(/<script[^>]+src="(\/[^"]+)"[^>]*defer/)![1];
const scriptUrl = ORIGIN + scriptPath;

// 3. Fetch and parse the script
const script = await send("GET", scriptUrl, scriptHeaders());
const scriptData = await roolink.parseScript(script.body);

// 4. Generate the sensor and post it, up to three times
for (let attempt = 0; attempt < 3; attempt++) {
  const { sensor } = await roolink.generateWebSensor({
    url: PAGE,
    userAgent: UA,
    _abck: await cookie("_abck"),
    bm_sz: await cookie("bm_sz"),
    scriptUrl,
    scriptData,
    language: "en-US",
    stepper: true,
    index: attempt,
  });
  await send("POST", scriptUrl, sensorHeaders(), JSON.stringify({ sensor_data: sensor }));
  if ((await cookie("_abck")).includes("~0~")) break;
}

// 5. Make the protected request
const cart = await send("POST", ORIGIN + "/cart/add", pageHeaders(), JSON.stringify({ sku: "123" }));
console.log(cart.status);

await site.destroySession();
await moduleClient.terminate();

If something goes wrong

The very first page request is blocked or returns an Akamai error page

Roolink is not involved yet. This is the connection itself: an HTTP library that does not look like Chrome, headers in the wrong order, or a proxy that changed IP. Route your script through powhttp and compare its requests with Chrome’s from your recording, header by header. Troubleshoot a block matches each symptom to its cause.

Roolink answers 401

The x-api-key header is missing or the key is wrong. Check the environment variable and that the SDK was created with it.

Roolink answers 422 with no device profile for user agent

Roolink builds sensors from real browser profiles and needs a User-Agent it has one for. Current desktop Chrome is the safe choice; send the identical string to the site. See Supported browsers.

The site says success but _abck never contains 0

The sensor was accepted but the connection is not trusted. Compare your page, script and sensor requests with Chrome’s in powhttp; header order and the sec-fetch-* values are the usual culprits. Some sites never flip the cookie to ~0~; on those, post three sensors and proceed to step 5.

The protected request fails even though _abck is valid

Check whether the site also runs SBSD, Sec-CPT or a pixel request in a browser; each has its own guide under Akamai Web. Confirm the IP did not change between steps, and keep every cookie the site set, not only _abck.

Next steps

Troubleshoot a blockWhich layer said no first, and what to change.

Sensor dataThe flow in depth: cookies, script rotation, stepper mode and every field.

SBSDThe second check many Akamai sites run alongside the sensor.

Sec-CPTThe proof-of-work challenge behind a 428.

Get started

Products

Solve your first Akamai challenge

The complete file

If something goes wrong

Next steps

​The complete file

​If something goes wrong

​Next steps

The complete file

If something goes wrong

Next steps