byVouched
API ReferenceBlogSign inGet started
GuidesDetectEnforceGovern

Reason codes

Machine-readable detection/* codes explaining why a verdict landed where it did

Machine-readable detection/* codes that say why a verdict landed where it did. Each code names one part of the evidence behind a result: how identity was verified (verificationMethod), which signals contributed (signals), and how the request was classified (detectionClass, isAiCrawler). The codes appear in the KYA-Reason-Codes response header, in stored detection records, and in the reasonCodes field of /api/v1/enforce responses when you set options.includeDetectionResult. A result lists its codes strongest evidence first and always carries at least one. New codes are added over time, so ignore any you don't recognize.

Verified attribution

CodeWhen it fires
detection/signature-verifiedverificationMethod is kya-http: the agent's KYA-OS request signature (RFC 9421) verified against the key its DID names.
detection/delegation-verifiedverificationMethod is kya-http-delegated: a delegation credential on the request verified.
detection/mcp-i-verifiedverificationMethod is mcp-i or mcp_i_handshake (legacy names, still emitted), or the new kya-os or kyaos_handshake: the KYA-OS handshake over MCP verified.
detection/did-signature-verifiedverificationMethod is did: the DNS gateway verified the agent's signed KYA-OS identity headers against its DID document.
detection/rfc9421-signature-verifiedverificationMethod is signature: the DNS gateway verified a vendor's HTTP message signature (RFC 9421) against the vendor's published keys.
detection/tier1-attribution-verifiedverificationMethod starts with tier1_ (for example tier1_rfc9421): the engine verified a vendor's HTTP message signature against the vendor's published key.
detection/a2a-verifiedverificationMethod is a2a: the security scheme an A2A Agent Card declares (an RFC 9421 key id, or a JWT bearer token checked against the agent's published keys) verified.
detection/verification-errorverificationMethod is error: a credential on the request was rejected during verification; the accompanying kyaErrorCode says why.

Structured evidence signals

CodeWhen it fires
detection/ua-pattern-matchSignal source user_agent_pattern: the User-Agent matched a known agent, crawler, or tool.
detection/header-heuristicSignal source header_heuristic: the request's headers showed signs of automation.
detection/ip-heuristicSignal source ip_heuristic: an IP-based heuristic matched.
detection/vendor-ip-corroboratedSignal source vendor_ip_feed: the request IP matched a known vendor's published IP range.
detection/ip-intelligence-proxy-signalSignal source ip_intelligence: IP intelligence flagged the request's true IP as a proxy, VPN, Tor, or anonymization exit.
detection/ja4-fingerprint-matchSignal source transport.ja4: the request's TLS fingerprint was recorded at the terminating proxy.
detection/client-integrity-failureSignal source client_integrity: integrity checks on the Pixel or Beacon report flagged it as not coming from the client it claims to.
detection/ua-tls-mismatchSignal source ua_tls_mismatch: the User-Agent claims a browser, but the TLS connection came from non-browser software.
detection/client-attribute-signalSignal source client.attributes: a client attribute the Pixel or Beacon reported contributed.
detection/behavioral-signalSignal source behavioural.interaction: a behavioral or interaction signal contributed.
detection/mcp-i-signalSignal source mcp_i: a KYA-OS identity proof was presented over MCP (evidence short of a completed handshake).
detection/kya-http-binding-signalSignal source kya_http_binding: a kya-http binding was presented (evidence short of full verification).
detection/kya-delegation-bearer-signalSignal source kya_delegation_bearer: a delegation bearer credential was presented.
detection/tier1-attribution-signalA signal whose source starts with tier1_: evidence from a vendor's request signature, short of (or alongside) full verification.
detection/a2a-card-signalSignal source a2a_agent_card: an A2A Agent Card was presented (evidence short of, or alongside, full verification).
detection/scanner-misclassification-hint-signalSignal source scanner_misclassification_hint: Cloudflare's bot score contradicted a human verdict that had no other evidence, so the request was classified incomplete_data.
detection/client-headless-escalation-signalSignal source client_headless_escalation: the Beacon reported automation evidence from the browser, which raised the classification.
detection/automation-default-viewportSignal source client_viewport_tell: an automation tool's default viewport (800x600), with reported behaviour and no interaction, classified the request as a bot.
detection/client-interaction-humanSignal source client_interaction: the request was classified human from interaction the client reported, with nothing pointing the other way. This is client evidence, not proven identity.
detection/cloudflare-bot-management-signalSignal source transport.cloudflare_bot_management: Cloudflare's bot-management score or verified-bot determination contributed.
detection/session-velocity-signalSignal source session_velocity: the client's request rate contributed.

Classification flags

CodeWhen it fires
detection/ai-crawler-flagisAiCrawler is true: classified as an AI training crawler (GPTBot, ClaudeBot, etc.), not an interactive agent.

Zero-evidence fallbacks

CodeWhen it fires
detection/zero-evidence-humandetectionClass is human, with no contributing signals and no verification: nothing matched.
detection/incomplete-data-overridedetectionClass is incomplete_data or unknown (or absent): the engine could not classify confidently.
detection/classified-without-signal-evidenceAny other class (ai_agent, bot or automation) with no contributing signals and no verification.

Detection in Enforce Mode

How Gateway and Middleware detect AI agents at the edge and server-side

Gateway Monitoring

Monitor Gateway health, performance, and detection metrics

On this page

Verified attributionStructured evidence signalsClassification flagsZero-evidence fallbacks