How the Edge Verify API Decides Access

This guide is for publishers and CDN or ESA integrators who want to know exactly what an edge gateway sends to the AISA verify endpoint and what happens next. You will be able to build the verify request, read the decision, and return the right response to the crawler. You will also be able to tell free, paid and blocked outcomes apart by status code and error value, and to see why the 402 body must reach the crawler untouched. The guide ends with a table of every verify outcome.

How the flow works

Before you start

• A gateway token issued by AISA out of band
• Publisher rules configured as allow, pay or block
• An edge gateway that can make server-side HTTPS calls

Step by step

1. Send the verify call before origin fetch

   When a crawler request hits the edge, call POST /api/v1/access/verify before going to origin. Put the gateway token in Authorization: Bearer. Forward the crawler's own token in X-Crawler-Token, which replaces the earlier name X-AISA-Crawler-Token still shown on older AISA pages. Always forward the original crawler user agent, because gateways rewrite User-Agent. X-Request-Id is optional and is echoed back for reconciliation.

   POST /api/v1/access/verify HTTP/1.1
   Host: cdn.aisa.one
   Authorization: Bearer YOUR_GATEWAY_TOKEN
   X-Crawler-Token: YOUR_CRAWLER_TOKEN
   X-ESA-Original-Crawler-Agent: ORIGINAL-CRAWLER-UA
   X-Request-Id: req-8c85ba19abef566b
   Content-Type: application/json

   S1 · esa.aisa.oneS3 · esa.aisa.oneS4 · esa.aisa.one

2. Build the JSON request body

   Send publisherDomain (the request Host) and resourceUrl (the path; query strings are stripped before rule matching). Add crawlerAgent: the identified bot id, or the original user agent if unidentified. Add crawlerAutoPrice set to true so a paid resource is charged in one call when the balance allows. crawlerAutoPrice, crawlerExactPrice and crawlerMaxPrice are mutually exclusive; sending none means price discovery. Save these fields as verify-body.json.

   # verify-body.json holds: publisherDomain, resourceUrl,
   # crawlerAutoPrice (true) and crawlerAgent
   curl -X POST https://cdn.aisa.one/api/v1/access/verify \
     -H 'Authorization: Bearer YOUR_GATEWAY_TOKEN' \
     -H 'X-Crawler-Token: YOUR_CRAWLER_TOKEN' \
     -H 'Content-Type: application/json' \
     --data @verify-body.json

   S2 · esa.aisa.oneS3 · esa.aisa.oneS4 · esa.aisa.one

3. Read accessGranted and decide

   A minimal gateway reads one field. When accessGranted is true, fetch the content from origin or cache and serve it with status 200. When it is false, do not serve content. Rules are first-match-wins: block gives 403 access_blocked, allow gives 200 free, pay needs a valid crawler token, and no matching rule gives 200 default allow with no charge. Charged responses carry charged and chargeAmount.

   S2 · esa.aisa.oneS3 · esa.aisa.one

4. Pass 402 and 403 bodies through unchanged

   On accessGranted false with statusCode 402 or 403, return statusCode and the verify JSON body to the crawler exactly as received. The body carries onboarding and a guidance block that teach a new crawler to register, fund a balance and retry with X-Crawler-Token. A 402 means payment can unlock the resource; a 403 access_blocked means payment will not help. Render your own block page if you want one, since AISA returns JSON only.

   S2 · esa.aisa.oneS3 · esa.aisa.one

5. Handle gateway-side failures separately

   A 401 gateway_unauthorized means the gateway token is missing or invalid, so check the key configured in the console; this is an operator error, not a crawler one. A 400 means a parameter problem such as invalid_price_format or conflicting price fields. A 500 internal_error is a provider fault, handled by your timeout and fault policy. On timeout retries, reuse the same X-Request-Id so both sides can reconcile charges.

   S2 · esa.aisa.oneS3 · esa.aisa.oneS4 · esa.aisa.one

Verify outcomes and gateway action

Common pitfalls

• Never send the crawler token in Authorization: Bearer; that header is reserved for the gateway layer and yields 401 gateway_unauthorized.
• Do not send crawlerAutoPrice, crawlerExactPrice and crawlerMaxPrice together; they are mutually exclusive and a conflict returns a 400.
• Do not rewrite or trim the 402 JSON. Its onboarding and guidance fields are how new crawlers learn to register and pay.
• The original-agent header is spelled X-ESA-Original-Crawler-Agent in AISA docs and X-Original-Crawler-Agent in the Open Verify spec; the body field crawlerAgent carries the same data.

Key takeaways

• Read accessGranted: true means fetch from origin, false means return statusCode and the JSON body to the crawler.
• 402 means payment can unlock the resource; 403 access_blocked means it cannot; 401 is reserved for the gateway layer.
• Send the crawler token in X-Crawler-Token and the gateway token in Authorization: Bearer, never mixed.

FAQ

How this page is made. Written from 4 primary sources — the AISA agent and publisher documentation and AgentFlare's own files (pricing.json, robots.txt, llms.txt, live responses, .data.json field lists). Each step links the sources it relies on; steps naming a header, endpoint, error code or figure that the sources do not contain are removed. Refreshed weekly.