> ## Documentation Index > Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt > Use this file to discover all available pages before exploring further. # Know Who's Behind Agent Traffic at the Edge > Check who an agent represents before its request reaches your origin. ## Overview At the edge, an agent acting for a verified customer can look the same as any other automated request. Without identity proof, the edge can't tell who the agent represents before deciding how to handle its traffic. Key challenges for edge and bot management teams: * Identifying agents acting for verified people * Checking that identity before the request reaches the origin * Passing a clear result to the origin without making it parse credentials * Preventing nonce reuse across every edge location * Adding identity to existing bot rules rather than replacing them KYA lets an agent present proof of the person it represents. The edge worker checks that proof with the KYA SDK and passes the result to the origin. KYA doesn't detect bots or score traffic. Existing bot rules still decide how to handle traffic without valid KYA proof. ## What happens to a request > [!NOTE] > > Parts of this playbook use the KYA SDK, which is coming soon. Those steps won't work until the packages are published. **1. The agent asks for access** The edge answers `401` with the KYA profile scope the site requires, in the `KYA-Disclosure-Scope` header. **2. The agent gets a nonce** The edge issues a one-time nonce from a store shared across all locations. **3. The agent presents its credential** It sends the credential and its signed proof to the token endpoint. **4. The edge checks the presentation** The SDK verifies the credential, agent signature, audience, nonce, expiry, revocation status and disclosure scope. See the [KYA SDK Quickstart](https://docs.baselayer.com/docs/kya-sdk-quickstart.md). **5. The edge passes the result to the origin** It removes any matching headers from the incoming request, then adds trusted headers with the result. **6. The origin decides** It applies its own access and risk rules. It doesn't need to parse the credential. See [Where to Run the Check](https://docs.baselayer.com/docs/kya-where-to-run-it.md). ## What the edge deployment requires * One reused verifier per worker instance * One nonce store shared by every location * An atomic check-and-spend for nonces * Result headers agreed between the edge and origin teams * Removal of those headers from incoming requests * A watch-only rollout before the result changes traffic handling > [!WARNING] > > Never trust result headers from the incoming request. Remove them at the edge before adding the verified result, or an agent could claim it already passed the KYA check. ## What each component sees | Component | What it sees | | - | - | | Edge worker | The credential presentation and the complete verification result. | | Origin | Only the trusted result the edge adds to the request. | | Agent | A one-time nonce, then the site's token if accepted. | | Baselayer | Requests for its public signing keys and revocation lists, which can be cached and don't identify the credential being checked. | ## What a refusal means A failed check means the credential or presentation couldn't be accepted. It isn't a bot score or an access decision. The edge or origin still decides how to handle the request. A credential either passes or fails with a typed reason, such as `CREDENTIAL_EXPIRED`, `CREDENTIAL_REVOKED`, `AUDIENCE_MISMATCH` or `NONCE_REPLAYED`. These are statements about whether the credential is valid. They are not risk scores, and the SDK never says to allow or block. The site's own rules make that call. Each nonce works once, and each credential works only for the site it was minted for and only with the agent key it was bound to. A credential copied off the wire can't be replayed. See [Handling Failures](https://docs.baselayer.com/docs/kya-handling-failures.md) for every code. ## Recommended settings | Setting | Recommendation | | - | - | | Verifier | One per worker instance, reused across requests. It holds the key and revocation list caches. The TypeScript SDK runs where WebCrypto Ed25519 and `fetch` exist, including Cloudflare Workers and other edge runtimes. | | `audience` | The site's domain, exactly as credentials are minted for it. `shop.example` and `www.shop.example` are different. | | Nonce store | One shared `NonceStore` for all locations, backed by Redis, a database or a Durable Object. See the note below the table. | | Result headers | Names the edge and origin teams agree on. Always remove them from incoming requests. | | Rollout | Watch-only first. Let the result affect traffic only after the team has reviewed watch-only results and defined its policy. | | Outages | `ISSUER_RESOLUTION_FAILED` and `STATUS_LIST_RESOLUTION_FAILED` are the only retryable failures. Decide whether to fail open (treat the agent as an unverified visitor) or closed (return `503`). The SDK never accepts a credential it couldn't check. | | Revocation | The revocation list is cached until its own refresh time, so a revoked credential stops passing in near-real time. | | Sandbox | Leave `allowSandbox` off in production. | > [!NOTE] > > **Nonce store** > > * `InMemoryNonceStore` only works within one process. > * `spend` must check and spend the nonce in one atomic step: in Redis, use `GETDEL`. > * Workers KV is not suitable. > * Nonces expire after 10 minutes by default. ## Next steps * Choose the edge architecture: [Where to Run the Check](https://docs.baselayer.com/docs/kya-where-to-run-it.md) * Implement the verifier: [KYA SDK Quickstart](https://docs.baselayer.com/docs/kya-sdk-quickstart.md) * Handle refusals and outages: [Handling Failures](https://docs.baselayer.com/docs/kya-handling-failures.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.