Python SDK for Castle

The official Python SDK for Castle. Castle analyzes user behavior in web and mobile apps to stop fraud before it happens.

This package is a thin wrapper around the Castle HTTP API. It exposes risk assessment, event logging, Lists, Privacy (GDPR), Events (enterprise), and webhook verification. See the API reference for supported events and payload shapes.

Requirements

• Python 3.9 or newer
• A Castle API secret

Installation

pip install castle

Quick start

importosfromcastle.configurationimportconfigurationfromcastle.clientimportClientconfiguration.api_secret=os.environ['CASTLE_API_SECRET']
client=Client.from_request(request)
verdict=client.risk({
'event': '$login',
'status': '$succeeded',
'request_token': request.POST.get('castle_request_token'),
'user': {'id': '12345', 'email': 'user@example.com'},
})
action=verdict.get('policy', {}).get('action') orverdict.get('action')
ifaction=='deny':
# block the userpasselifaction=='challenge':
# send 2FA / additional verificationpasselse:
# allowpass

Client.from_request builds request context (IP, headers, client id) from a framework request object. See Advanced configuration for header allow/deny lists and proxy chains.

Configuration

The minimal, recommended setup:

importosfromcastle.configurationimportconfigurationconfiguration.api_secret=os.environ['CASTLE_API_SECRET']
# Behavior when Castle's API is unreachable or returns a 5xx.# One of: allow (default), deny, challenge, throwconfiguration.failover_strategy='allow'# Request timeout in milliseconds (default: 1000).# RequestError is raised on timeout.configuration.request_timeout=1000

Logging

importloggingfromcastle.configurationimportconfigurationconfiguration.logger=logging.getLogger('castle')

The logger only needs to respond to info. Each request and response is logged with sensitive values stripped.

Multi-environment / multi-tenant

Most apps only need the global configuration singleton, but you can also create standalone Configuration instances and pass them per call via APIRequest:

fromcastle.configurationimportConfigurationfromcastle.api_requestimportAPIRequestfromcastle.commands.riskimportCommandsRiskconfig=Configuration()
config.api_secret=os.environ['CASTLE_API_SECRET_TENANT_A']
APIRequest(config).call(CommandsRisk(context).call({
'event': '$login',
'status': '$succeeded',
'request_token': '<token>',
'user': {'id': '1234'},
}))

Usage

See Castle documentation and the API reference for endpoint details, event types, and integration guides.

Advanced configuration

The defaults work for most deployments. The options below only matter if you have a non-trivial proxy chain or strict header policies.

Header allow/deny lists

By default the SDK sends every HTTP header except Cookie and Authorization. Castle uses these headers to fingerprint the request.

fromcastle.configurationimportconfiguration, DEFAULT_ALLOWLIST# Always-blocked headers (in addition to Cookie/Authorization).configuration.denylisted= ['HTTP-X-Internal-Header']
# Strict allow-list mode. Headers outside the list are scrubbed,# except User-Agent which is always preserved.configuration.allowlisted=DEFAULT_ALLOWLIST

Header names are case-insensitive and accept both _ and - as separators. A leading HTTP_ prefix is stripped automatically.

Client IP detection

Castle needs the original client IP, not the IP of your proxy or load balancer. The SDK reads X-Forwarded-For and Remote-Addr by default; pick one of the strategies below:

fromcastle.configurationimportconfiguration, TRUSTED_PROXIES# 1. Custom header (e.g. Cloudflare's Cf-Connecting-Ip).configuration.ip_headers= ['Cf-Connecting-Ip']
# 2. Static, known proxy IPs (strings or regexes).configuration.trusted_proxies= ['10.0.0.1']
# 3. Ephemeral proxies but known chain depth.configuration.trusted_proxy_depth=2# 4. Last resort: trust the entire X-Forwarded-For chain.# Warning: vulnerable to header spoofing if a malicious proxy is in path.configuration.trust_proxy_chain=False

Use eithertrusted_proxiesortrusted_proxy_depth, not both. Private/loopback ranges in TRUSTED_PROXIES are always considered trusted.

Optional settings

fromcastle.configurationimportconfiguration# Override the API base URL (default: https://api.castle.io/v1)# configuration.base_url = 'https://api.castle.io/v1'

Signature

Secure mode signs user identifiers on the server:

fromcastle.secure_modeimportsignaturesignature(user_id)

Exceptions

All exceptions inherit from CastleError. The most useful ones:

• ConfigurationError — the SDK is misconfigured (missing API secret, invalid URL, etc.)
• RequestError — network failure or timeout reaching Castle
• InvalidRequestTokenError — the request token is missing or invalid
• InvalidParametersError — 422 response with validation details
• RateLimitError — 429 response; back off and retry
• UnauthorizedError — 401; bad API secret
• InternalServerError — 5xx response from Castle
• WebhookVerificationError — webhook signature did not match

The full list is in castle/errors.py.