Skip to main content

​
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

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.
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.

​
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
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

​
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 for every code.
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