Dokumentation

API Referenz

Die wichtigsten Endpunkte: Token holen (challenge) und Token prüfen (verify).

Endpoints

challenge (Token) & verify (Entscheidung).

POST/v1/challenge

Widget holt Token (kurzlebig)

json

{ "siteKey": "sk_...", "action": "contact", "sid": "scs_…", "meta": { "ttf": 2.4, "hp": 0, "vc": 1 } }

POST/v1/verify

Server prüft Token + Secret

json

{ "siteKey": "sk_...", "secret": "sec_...", "token": "v4.local....", "sid": "scs_…", "action": "contact" }

Verify Response

Du bekommst ok/score/decision/reason. Bei Limits kann 402 kommen.

json

{ "ok": true, "score": 0.86, "decision": "allow", "reason": "ok", "plan": "growth", "threshold": 0.6 }

Was du im Client/Backend tun solltest.

400 missing_token / missing_params / invalid_token / replay_or_expired → Submission blocken. Ohne Token trotzdem /v1/verify aufrufen (mit leerem token), damit der Block im Dashboard gezählt wird.
401 invalid_secret → Secret prüfen (Rotate?).
403 Origin not allowed / Action not allowed → Domain bzw. Action im Dashboard unter „Websites & Keys“ freigeben. Erscheint auch unter Auswertung → Blockiert.
402 payment_required / plan_limit → Upgrade-Hinweis anzeigen.
409 no_valid_mandate (Billing) → Checkout starten.
429 rate_limited → Retry / Backoff / IP-Limit.