RiskShield Guard integration guide

Integration modes

RiskShield Guard supports two integration modes. The MVP uses only the first:

1. SDK / middleware mode (MVP) — Your server calls POST /api/v1/protect/assess before sensitive endpoints and enforces the decision (ALLOW, DELAY, CHALLENGE, BLOCK). No traffic is proxied through RiskShield.
2. Reverse-proxy mode (optional) — Your reverse proxy (e.g. Nginx, Envoy) calls the same Assess API and enforces allow/challenge/block at the edge before traffic reaches your origin. See the Reverse-Proxy Mode guide for architecture, header contract, security, and examples.

Assess flow

Before a sensitive action (login, payment, form submit), your server calls:

POST /api/v1/protect/assess

Send a JSON body with site_id (or public_site_key), endpoint, method, headers, optional return_url (allowlisted), and optional client_signals, session_id, action_type. Do not send ip — the server uses the connection IP. If the client has a pass token, include it as pass_token or X-Riskshield-Pass-Token.

Response: decision, reason_code, risk_score. When a challenge is required: challenge_url (includes challenge_id and return_url if allowlisted) and challenge_id. The challenge page fetches token/difficulty from GET /challenge/pow.

Enforcing the decision

• ALLOW — Proceed with the action.
• DELAY — Wait delay_ms (from the response), then proceed.
• CHALLENGE_POW / CHALLENGE_OTP — Redirect the user to challenge_url (your RiskShield domain + path). After they pass, they are redirected to your return_url with ?riskshield_pass_token=.... Store that token and send it with the next assess call or verify it.
• BLOCK — Return 403 and do not proceed.

Only allow return_url values that are in your site's domain allowlist (configured in the RiskShield Guard dashboard). Enforced in the backend when building challenge_url and when redirecting after success.

Token verification

You can verify a pass token in two ways:

• API — POST /api/v1/protect/token/verify with body { "pass_token": "...", "site_id": 1 }. Returns valid and claims.
• Local (server-only) — Use your stored secret key to verify the token signature with HMAC-SHA256 on the token payload. See the full algorithm and Python example in docs/BOTGUARD_INTEGRATION.md in your repository.

Challenge URLs

Hosted by RiskShield (RiskShield247.com):

• PoW: https://riskshield247.com/c/{public_site_key}/pow?challenge_id={challenge_id}&return_url={encoded_return_url}
• OTP: https://riskshield247.com/c/{public_site_key}/otp?return_url={encoded_return_url}

Protection badge

When your integration runs a security check, visitors who need to complete a challenge are sent to RiskShield-hosted pages (PoW or OTP). The "Protected by RiskShield" badge is displayed automatically on those pages — no code to add. Visitors see that the site is protected and can click through to learn more about RiskShield.

Integration examples by language

import time
import requests
from django.http import HttpResponseRedirect, JsonResponse

GUARD_ASSESS_URL = "https://riskshield247.com/api/v1/protect/assess"
SITE_ID = 1

def guard_check(request):
    return_url = request.build_absolute_uri(request.get_full_path())
    resp = requests.post(
        GUARD_ASSESS_URL,
        json={
            "site_id": SITE_ID,
            "endpoint": request.path,
            "method": request.META.get("REQUEST_METHOD", "GET"),
            "headers": {"user-agent": (request.META.get("HTTP_USER_AGENT") or "")[:512]},
            "action_type": "LOGIN",
            "return_url": return_url,
        },
        timeout=5,
    )
    data = resp.json()
    if data.get("decision") == "BLOCK":
        return JsonResponse({"detail": "Access denied."}, status=403)
    if data.get("decision") in ("CHALLENGE_POW", "CHALLENGE_OTP"):
        base, path = "https://riskshield247.com", data.get("challenge_url", "")
        return HttpResponseRedirect(base + path if path.startswith("/") else base + "/" + path)
    if data.get("decision") == "DELAY" and data.get("delay_ms"):
        time.sleep(min(data["delay_ms"], 1500) / 1000.0)
    return None