Trust API Design Principles: What Makes a Good Request Evaluation Contract

The design properties that make a request trust API reliable, safe to integrate, and resistant to information leakage.

Stable decisions over raw scores

An API that returns a structured decision — ALLOW, CHALLENGE, or BLOCK — is simpler to integrate than one that returns a raw score and expects the caller to implement threshold logic.

Stable decision enums also allow the provider to adjust internal thresholds as the threat landscape changes without requiring integration changes from the caller. The contract is the decision, not the number that produced it.

Public reason categories must not leak private logic

Exposing detailed internal evidence in API responses creates an adversarial feedback loop. If the API says "blocked because JavaScript execution was absent," attackers add JavaScript execution. If it says "blocked because user-agent matched a known bot pattern," attackers change their user-agent.

Public reason categories should be broad enough to be actionable for logging and user communication without being specific enough to guide evasion. Categories like network_risk, identity_risk, and automation_risk communicate what dimension of risk triggered the decision without revealing the specific check.

Timeouts and fallback behavior are part of the contract

An API that does not specify timeout behavior leaves integrators to guess. A good trust API contract includes a recommended timeout, a maximum timeout, and explicit guidance on fallback behavior when the timeout fires.

The API should also be designed to respond under its SLA even under load. Latency percentile guarantees — not just average response time — should be part of the published contract.