Pular para o conteúdo

Prosopo Protect at the Edge

Este conteúdo não está disponível em sua língua ainda.

Prosopo Protect can run at the edge of your CDN so blocked and challenged requests never reach your origin. Two integrations are supported today:

Both integrations enforce the same policy: they consult the Prosopo Protect API on every incoming request and act on the returned verdict before it reaches your origin.

How it works

Section titled How it works

On every request that hits your CDN:

  1. If the request has a prosopo_session cookie the edge fetches the verdict for the session’s token from the Prosopo Protect API. allow passes through to your origin; block returns a branded interstitial (or JSON error for API calls) with no origin fetch; challenge serves a captcha interstitial.
  2. If the request has no cookie the edge asks Protect what to do. Protect evaluates your access-rule set (IP CIDR, ASN, IP category, country, User-Agent, JA4 TLS fingerprint) against the request. Rule matches return block or challenge; if no rule matches and the path is an HTML page, the edge lets it through so the Protect script can create a session.

The blocked-response HTML and challenge interstitial are branded per site via your Prosopo dashboard: logo, colour palette, typography, and message strings all sanitised and rendered server-side by the edge.

Protecting HTML pages vs JSON APIs

Section titled Protecting HTML pages vs JSON APIs

Protect handles browser page loads and API calls differently. You tell it which paths on your site are which, and the edge enforces accordingly.

HTML paths — pages users load in a browser

Section titled HTML paths — pages users load in a browser
  • First visit (no cookie): the edge passes the request through so the Protect script embedded in your HTML can load and create a session.
  • Subsequent requests: the edge fetches the verdict and either forwards (allow), serves a captcha interstitial (challenge), or serves a branded “Access Denied” page (block).

Session creation is transparent — the Protect script calls /api/protect/init, receives a prosopo_session cookie, and every request from that browser carries it automatically.

JSON paths — API endpoints called by scripts / XHR / fetch

Section titled JSON paths — API endpoints called by scripts / XHR / fetch
  • No cookie: the edge returns 401 Unauthorized with X-Prosopo-Status: no-session. The Protect script (loaded on your site’s HTML pages) intercepts the 401, creates a session, and replays the request.
  • With cookie: the edge fetches the verdict. allow forwards to your origin; block returns a JSON error the Protect script uses to render an in-place block interstitial; challenge returns a JSON challenge_config the script uses to render a captcha modal without a full-page reload.

JSON paths never pass through on a cookie-less request — an API endpoint isn’t an HTML page, so there’s nowhere for the Protect script to load from and no session can be bootstrapped on the fly. A first-hit is always either a rule-based decision or a hard 401.

Configuring path types

Section titled Configuring path types

Tell Protect which paths on your site are HTML vs JSON on your Prosopo dashboard:

  • Site-level default (defaultPathType) — applies to every path unless overridden.
  • Per-endpoint rules — override the default for specific paths (e.g. /api/* → json, / → html).

This closes the “spoof Accept: text/html on an API endpoint” bypass. Bots can lie about their Accept header, but they can’t change what content type your site actually serves at a given path — the declared type is what the edge enforces.

Which mode fits your site

Section titled Which mode fits your site
Your siteRecommended defaultEndpoint overrides
Server-rendered pages with occasional API endpointshtml/api/* → json
Single-page app with a heavy API surfacejson/, /index.html → html
Pure JSON API service (no HTML at all)json(none)

For a pure-API deployment, consumers must obtain a session through a separate app that loads the Protect script, or through your own headless-friendly flow — the edge won’t let a cookie-less browser reach a JSON endpoint.

Correlation

Section titled Correlation

Every edge request is stamped with an X-Prosopo-Request-Id header that’s echoed on the response and written to the verdict audit log. From a support ticket you can grep straight to the verdict that fired.

What’s next

Section titled What’s next

Pick your platform:

Before you deploy, your Prosopo site must be registered with the Protect service. Site registration is handled from your Prosopo dashboard or by your Prosopo account manager — you will need the site’s SS58 key (e.g. 5HSuC1s…) and a CLIENT_JWT signed by the site’s key to authenticate the edge to the Protect API.