skalaio 0.2.0

Python SDK for the Skala fraud detection API

Skala Python SDK

Python SDK for the Skala fraud detection API.

Requires Python 3.11+.

Install

pip install skalaio

Quick Start

from skala import Skala, SkalaOptions, ScoreRequest

skala = Skala(SkalaOptions(api_key="sk_live_..."))

result = skala.score(ScoreRequest(
    event_type="signup",
    ip=req.ip,
    email=body.email,
    user_agent=req.headers["user-agent"],
))

if result.decision == "block":
    return {"error": "Request blocked"}, 403

if result.decision == "step_up":
    return {"requires_verification": True}, 200

Report an Outcome

Feed back fraud signals to improve future scoring:

from skala import OutcomeRequest

skala.outcome(OutcomeRequest(
    request_id=result.request_id,
    outcome="confirmed_fraud",
))

Timeout Fallback

score() auto-allows when the API is unreachable (timeout or network failure), so scoring does not block user traffic.

HTTP API responses (for example 4xx/5xx) still raise errors.

result = skala.score(...)

if hasattr(result, "fallback") and result.fallback:
    # request was auto-allowed by SDK fallback
    # result.reason_codes is SDK_TIMEOUT_FALLBACK or SDK_NETWORK_FALLBACK

Error Handling

Use structured SDK errors for predictable handling:

from skala import (
    SkalaApiError,
    SkalaNetworkError,
    SkalaTimeoutError,
)

try:
    skala.outcome(OutcomeRequest(request_id="req_123", outcome="confirmed_fraud"))
except SkalaTimeoutError:
    # request timed out
except SkalaNetworkError:
    # API unreachable (DNS/TLS/connectivity)
except SkalaApiError as e:
    # API returned non-2xx
    print(e.status, e.body, e.request_id)

Configuration

from skala import Skala, SkalaOptions

skala = Skala(SkalaOptions(
    api_key="sk_live_...",
    base_url="https://apiskala.varityweb.com",  # default
    timeout_ms=5000,                             # default
    retries=2,                                   # default, only retries 5xx
))

License

MIT