Skip to main content

What you will build. A small script that finds Kasada’s challenge on a site, fetches its script, asks Roolink for the answer, posts it back, and comes away with the session token and cookies the site wants on every request after that.

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. Kasada is plain JSON over HTTPS, so the examples call the API with your language’s standard HTTP client; the SDKs wrap the same three endpoints if you prefer them.

  • Kasada is the protection in front of the site. It hands every new visitor a puzzle script and only serves real content to visitors whose answer looks like a browser produced it.
  • ips.js is that puzzle script. Its path contains two random identifiers and changes per site.
  • The payload is the answer. Roolink generates it from the script; you post it to Kasada’s /tl endpoint.
  • x-kpsdk-ct is the token Kasada gives you once the payload is accepted. x-kpsdk-st is the timestamp that came with it. Together with the cookies they are your session.
  • The fingerprint endpoint, /fp, is how most sites start the challenge: the page loads, and a hidden frame fetches /fp, which answers 429 or 200 with the puzzle. A few sites answer 429 on the very first page load instead; that is the initial block page variant.
1Set up

Put your API key and proxy URL in environment variables and install a TLS client for your language. Kasada checks the connection the same way Akamai does, so an ordinary HTTP library is refused before the payload matters.

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

2Request the fingerprint endpoint

In your recording, find the request the page made to a path ending in /fp with an x-kpsdk-v query parameter, something like /7c1e4a2b-.../b58f0c61-.../fp?x-kpsdk-v=j-1.2.779. The browser loaded it in a hidden frame right after the page. Request that URL yourself with the headers from the recording, sending the page URL as referer.

The answer is a small HTML page with one <script> tag pointing at ips.js in the same directory. That is the challenge. Most sites send it with 429; some, Nike among them, send the same page with 200.

You should see a 429 or 200 and exactly one script URL ending in /ips.js.

3Fetch the script and ask Roolink for the payload

Download ips.js through the same session, with the script headers from your recording. Then send Roolink four things: the script body exactly as fetched, the URL you fetched it from, the page URL as referer, and your User-Agent and language. Roolink returns two things: a payload, base64-encoded, and a headers object.

Roolink picks a real browser profile matching your User-Agent, so send the same string you send the site. The /payload call is the one that counts against your plan.

You should see a JSON response with headers containing x-kpsdk-ct, x-kpsdk-dt, x-kpsdk-im and x-kpsdk-v, and a long payload string.

4Post the payload to /tl

Kasada’s /tl endpoint lives in the same directory as ips.js. Post the decoded payload bytes to it as application/octet-stream, through the same session, with the browser’s /tl headers from your recording plus the four x-kpsdk-* headers Roolink returned, in the order the browser sent them.

Kasada answers 200 with the body {"reload": true}. Two response headers matter: x-kpsdk-ct, your session token, and x-kpsdk-st, its timestamp. The response also sets Kasada’s cookies. Keep all three.

You should see {"reload":true} and non-empty x-kpsdk-ct and x-kpsdk-st response headers.

5Load the page again

Request the page you started from, through the same session. The cookies from /tl are what Kasada checks for a plain page load, so this time it serves the real page rather than the challenge. Follow redirects on the same origin if the site sends any.

That is a solved challenge. What comes next depends on the site. Many serve everything on the strength of the cookies alone. Sites that protect their API calls also expect a fresh proof of work, x-kpsdk-cd, on each one; the Proof of work page shows how to add it using the ct and st you just saved.

You should see a 200 with the page’s real content and no ips.js script tag in it.

The complete file

The four header sets are left for you to fill from your powhttp recording: the page load, the /fp frame, the script, and the /tl post. Copy each list in the order powhttp shows it. The /tl set is the browser’s own headers; the x-kpsdk-* values from Roolink are merged in by the code.

If something goes wrong

A 200 without the script means the session is already trusted, usually because cookies from an earlier run are still in the jar. Start with an empty jar. A 403 or a block page from a different vendor means the site is not behind Kasada, or not on this path.
Anything other than 200 with {"reload":true} means Kasada refused the payload. The usual causes, in order: the /tl headers or their order differ from the browser’s; the User-Agent sent to the site differs from the one sent to Roolink; the session changed IP between /fp and /tl.
The cookies from the /tl response did not make it into the request. Confirm the same session and jar are used throughout, and that you request the page on the same origin the challenge came from.

Next steps

Proof of workAdd a fresh x-kpsdk-cd to each protected API request, and refresh ct as responses update it.
Initial block pageThe variant where the very first page load returns the challenge.
Vercel BotIDThe x-is-human header for endpoints protected by Vercel’s BotID, which runs on Kasada.
API referenceEvery field of the payload, proof-of-work and BotID endpoints.