> For the complete documentation index, see [llms.txt](https://docs.apexsolutions.lol/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apexsolutions.lol/aws-waf/getting-started.md).

# Getting Started

How AWS WAF works, how to tell a site uses it (Challenge and CAPTCHA), and what the solves return.

If you already know how AWS WAF works, skip to the **API reference**. This page explains what it is, how to tell a site uses it, and how the whole flow fits together — you do not need to reverse-engineer anything.

## Understanding AWS WAF

AWS WAF is a managed web firewall. Many sites enable its bot control, which serves a **JavaScript challenge** to visitors: the page loads a `challenge.js` script (from a `*.token.awswaf.com` host) that runs a proof-of-work in the browser, collects a fingerprint, and — when the proof checks out — issues an **`aws-waf-token`** cookie. Until the site has a valid token for the session, protected actions are blocked or capped.

Some sites go further and serve the interactive **CAPTCHA**: a 9-tile image grid (*"select all the tiles that contain X"*). That flow is driven by a second script (`captcha.js` from `*.captcha.awswaf.com`), runs through `/problem` → `/verify` → `/voucher`, and yields a separate **`aws-waf-captcha-token`** cookie.

The tokens are **not** one-shot values you submit to a backend like a reCAPTCHA token. They are **cookies** your client carries on requests to the protected site; the site's WAF checks them and lets traffic through.

## Identifying AWS WAF

Before solving, confirm the site actually uses AWS WAF:

1. **The 405/202 with `x-amzn-waf-action`.** A blocked request comes back `405` (or `202`) with the header `x-amzn-waf-action: challenge` (Challenge) or `x-amzn-waf-action: captcha` (CAPTCHA). That response is an interstitial HTML.
2. **The SDK scripts.** The interstitial HTML references `challenge.js` from `*.token.awswaf.com` and (for the CAPTCHA) `captcha.js` from `*.captcha.awswaf.com` — same `{id}.{region}` prefix and 3-segment path.
3. **`window.gokuProps`.** The CAPTCHA interstitial embeds `window.gokuProps = {key, iv, context}`.
4. **The cookies.** After a successful solve the browser holds `aws-waf-token` (and `aws-waf-captcha-token` for the CAPTCHA), `aws-waf-uid` and `awswaf_session_storage` cookies.

> **There are two separate providers/endpoints**: the Challenge (`waf.apexsolutions.lol/payload`) and the CAPTCHA (`waf.apexsolutions.lol/captcha`). Check `x-amzn-waf-action` in your traffic to pick the right one.

## How a session is built

There is no long-lived session. Apex uses the params you extract from your traffic (params-driven: the client parses its own requests, the solver never re-discovers the target):

* **Challenge**: you send the `challenge_url` (the base of the `challenge.js` script from your traffic) + the exact `page_url` + `user_agent` + `proxy`. Apex completes the proof-of-work (HashcashScrypt, SHA256 or NetworkBandwidth), builds a realistic browser fingerprint, and submits it. When AWS WAF accepts it, the response contains an **`aws-waf-token`**.
* **CAPTCHA**: you send `token_host` + `captcha_host` + `goku_props` + `page_url` (all from the 405 interstitial) + `user_agent` + `proxy`. Apex mints the invisible token (or re-uses your `existing_token`), fetches the image grid, solves it with a vision-AI model, and exchanges the voucher for an **`aws-waf-captcha-token`**.

## Solution Flow

1. **Identify the protected page** and capture the AWS WAF interstitial from your traffic (`challenge_url` for the Challenge; `token_host`/`captcha_host`/`goku_props` for the CAPTCHA). Note your browser's user agent (Google Chrome on Windows).
2. **Solve through Apex.** Send the extracted params + your user agent + your proxy. Apex returns the token. See the API reference for the exact request.
3. **Replay the token.** Send it as the `aws-waf-token` (or `aws-waf-captcha-token`) cookie on your requests to the protected site, with the same user agent and the same proxy IP.

## Important Notes

{% hint style="info" %}
**The token is a cookie to replay, not a backend value.** Attach it as the `aws-waf-token` / `aws-waf-captcha-token` cookie on the requests to the protected page. The `user_agent` must be **Google Chrome on Windows** and match the browser your client uses. Use a **sticky-session proxy** (same IP for the whole session): AWS WAF rate-limits per source IP and tokens are tied to the IP that minted them.
{% endhint %}