Skip to main content

Castle protects your users from account compromise

Project description

Build Status

Castle analyzes device, location, and interaction patterns in your web and mobile apps and lets you stop account takeover attacks in real-time.


pip install castle


Import and configure the library with your Castle API secret.

from castle.configuration import configuration, DEFAULT_ALLOWLIST

# Same as setting it through Castle.api_secret
configuration.api_secret = ':YOUR-API-SECRET'

# For authenticate method you can set failover strategies: allow(default), deny, challenge, throw
configuration.failover_strategy = 'deny'

# Castle::RequestError is raised when timing out in milliseconds (default: 1000 milliseconds)
configuration.request_timeout = 1500

# Base Castle API url
# configuration.base_url = ""

# Logger (need to respond to info method) - logs Castle API requests and responses
# configuration.logger = logging.getLogger()

# Allowlisted and Denylisted headers are case insensitive
# and allow to use _ and - as a separator, http prefixes are removed
# By default all headers are passed, but some are automatically scrubbed.
# If you need to apply an allowlist, we recommend using the minimum set of
# standard headers that we've exposed in the `DEFAULT_ALLOWLIST` constant.
# Allowlisted headers
configuration.allowlisted = DEFAULT_ALLOWLIST + ['X_HEADER']

# Denylisted headers take advantage over allowlisted elements. Note that
# some headers are always scrubbed, for security reasons.
configuration.denylisted = ['HTTP-X-header']

# Castle needs the original IP of the client, not the IP of your proxy or load balancer.
# The SDK will only trust the proxy chain as defined in the configuration.
# We try to fetch the client IP based on X-Forwarded-For or Remote-Addr headers in that order,
# but sometimes the client IP may be stored in a different header or order.
# The SDK can be configured to look for the client IP address in headers that you specify.

# Sometimes, Cloud providers do not use consistent IP addresses to proxy requests.
# In this case, the client IP is usually preserved in a custom header. Example:
# Cloudflare preserves the client request in the 'Cf-Connecting-Ip' header.
# It would be used like so: configuration.ip_headers=['Cf-Connecting-Ip']
configuration.ip_headers = []

# If the specified header or X-Forwarded-For default contains a proxy chain with public IP addresses,
# then you must choose only one of the following (but not both):
# 1. The trusted_proxies value must match the known proxy IPs. This option is preferable if the IP is static.
# 2. The trusted_proxy_depth value must be set to the number of known trusted proxies in the chain (see below).
# This option is preferable if the IPs are ephemeral, but the depth is consistent.

# Additionally to make X-Forwarded-For and other headers work better discovering client ip address,
# and not the address of a reverse proxy server, you can define trusted proxies
# which will help to fetch proper ip from those headers

# In order to extract the client IP of the X-Forwarded-For header
# and not the address of a reverse proxy server, you must define all trusted public proxies
# you can achieve this by listing all the proxies ip defined by string or regular expressions
# in the trusted_proxies setting
configuration.trusted_proxies = []
# or by providing number of trusted proxies used in the chain
configuration.trusted_proxy_depth = 0
# note that you must pick one approach over the other.

# If there is no possibility to define options above and there is no other header that holds the client IP,
# then you may set trust_proxy_chain = true to trust all of the proxy IPs in X-Forwarded-For
configuration.trust_proxy_chain = false
# *Warning*: this mode is highly promiscuous and could lead to wrongly trusting a spoofed IP if the request passes through a malicious proxy

# *Note: the default list of proxies that are always marked as "trusted" can be found in: Castle::Configuration::TRUSTED_PROXIES

Multi-environment configuration

It is also possible to define multiple configs within one application.

from castle.configuration import Configuration

# Initialize new instance of Castle::Configuration
config = Configuration()
config.api_secret = ':YOUR-API-SECRET'

After a successful setup, you can pass the config to any API command as follows:

from castle.api.get_device import APIGetDevice

# Get device data, config)


Here is a simple example of track event.

from castle.client import Client

castle = Client.from_request(request)
  'event': '$login.succeeded',
  'user_id': 'user_id'

The client will automatically configure the context for each request.


from secure_mode import signature


will create a signed user_id.

Async tracking

By default Castle sends requests synchronously. To send requests in a background worker you can generate data for a worker:

from castle.payload.prepare import PayloadPrepare

payload =
      'event': '$login.succeeded',
      'properties': { 'key': 'value' },
      'user_traits': { 'key': 'value' }

and use it later in a way

from castle.client import Client

client = Client(context)


List of Recognized Events can be found in the docs.

Device management

This SDK allows issuing requests to Castle’s Device Management Endpoints. Use these endpoints for admin-level management of end-user devices (i.e., for an internal dashboard).

Fetching device data, approving a device, reporting a device requires a valid device_token.

from castle.api.get_device import APIGetDevice

# Get device data
from castle.api.approve_device import APIApproveDevice

# Approve a device
from castle.api.report_device import APIReportDevice

# Report a device

Fetching available devices that belong to a given user requires a valid user_id.

from castle.api.get_devices_for_user import APIGetDevicesForUser

# Get user's devices data


CastleError will be thrown if the Castle API returns a 400 or a 500 level HTTP response. You can also choose to catch a more finegrained error.


Castle uses webhooks to notify about $incident.confirmed or $review.opened events. Each webhook has X-Castle-Signature header that allows verifying webhook’s source.

from castle.webhooks.verify import WebhooksVerify

# Verify the webhook, passed as a Request object
# WebhookVerificationError is raised when the signature is not matching


Documentation and links to additional resources are available at

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for castle, version 6.0.0
Filename, size File type Python version Upload date Hashes
Filename, size castle-6.0.0-py2.py3-none-any.whl (64.0 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size castle-6.0.0.tar.gz (23.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page