Add an inspectable assessment to an application action.

Blokk’s bot detection API sits behind your application’s own validation. Your backend requests an assessment for a configured action, your application owns the response and your team can report a later confirmed outcome.

Integrate where the action reaches your backend.

A contact submission, account action or request that consumes credits has a server-side decision point. Blokk’s generic integration adds automation evidence at that point. Keep authentication, authorisation, CSRF checks, rate controls and input validation in your own application. An assessment does not replace them.

Start in shadow mode: the normal operation continues under your existing controls while you inspect assessments. This lets you check the integration and review the available evidence before defining a policy that changes a user’s experience.

Follow the API lifecycle.

1. Prepare an attempt. Your backend calls POST /v1/attempts with a configured action, expected origin, server-derived session binding and submission identifier. Keep the API key on your server.
2. Collect optional browser evidence. The browser can send a bounded observation to POST /v1/collect and receive an opaque receipt. Browser observations are assertions; a receipt does not establish that they are truthful.
3. Validate and assess. After your normal request checks, your backend calls POST /v1/assess. Blokk checks the binding and integrity, applies versioned rules and stores the assessment.
4. Record the actual action. Keep the assessment and policy recommendation distinct from what your application executed. Shadow mode does not block the request.
5. Report a reviewed outcome. Use POST /v1/outcomes when your team establishes what happened. Include the basis for the finding and action taken; preserve unresolved cases and later corrections.

Read the API and SDK examples for the working contract, and follow the setup and testing guide before evaluating the local lab.

Choose the evidence binding your integration needs.

Make retries and failure handling part of the design.

An exact retry reuses the stored assessment. Altered input under the same idempotency key is rejected. Your application must also make its own business operation idempotent: reusing an assessment does not stop your code from sending two messages or consuming credits twice.

Missing browser evidence, an invalid request and a service outage are different cases. The server SDK distinguishes invalid requests from unavailability. In the default shadow integration, an unavailable detector leaves the normal action running under your existing controls, with no assessment received by your application. A timed-out request may already have been recorded by the API; preserve the exact retry identifiers when checking its result.

Test the contract before judging detection value.

• Check an ordinary submission, missing optional evidence and a valid exact retry.
• Check expired or mismatched binding and altered input under an existing idempotency key.
• Exercise the unavailable-service path and confirm your business action still follows its intended controls.
• Record a reviewed outcome and correction without rewriting the original assessment.

Northstar and Quillmark are fictional local integration fixtures. Their scripted results check defined scenarios; they do not establish real-world detection performance. Browser evidence is limited and some automation is missed. The developer overview explains compatibility and data boundaries.

Review the first commercial integration.

The Shopify pilot focuses on one recurring merchant problem. Read the research notes for practical discussions of evidence, monitoring and policy.