Sandbox environments

Every Castle environment is either a production environment or a sandbox environment. A sandbox environment has its own API keys and its own data, and is made for integration work and testing before an integration goes live.

Scoring is the same as production

A sandbox environment runs the same detection pipeline as production. Device signals, aggregations, custom signals, lists, and risk policies are all evaluated in the same way, and the Bot score and Abuse score are calculated with the same models.

A score can still differ between the two environments. The cause is the traffic, not the environment type. A sandbox environment usually sees a small amount of synthetic traffic, and signals that depend on history, for example new device and multiple accounts per device, need volume before they behave as they do in production.

Mock request tokens

A sandbox environment accepts Mock Request Tokens. A production environment rejects them.

A mock request token is a readable string with parameters in it. Two of those parameters, risk and policy.action, set the Abuse score and the policy action that Castle returns:

test|device:chrome_on_mac|ip:us-ca|policy.action:allow

The request_token comes from the browser or the mobile client, so the client controls its value. A real token is an opaque string, and a client cannot forge one or change what it means, so the client has no influence on the outcome. A mock token is different, because the client writes the policy action into the token and Castle returns it.

A sandbox response therefore shows what the client asked for, not what Castle decided. Use a production environment for any test that must prove a control works.

Rate limits

A sandbox environment has its own rate limits. The limits below are absolute maximums that apply to every sandbox environment and cannot be raised:

The effective limit can be lower. The rate limit of the plan applies as well, and the lower of the two decides when a request is refused.

A refused request gets an HTTP 429 response with the error type too_many_requests. Each response carries the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Sandbox requests count toward the API call volume of the plan, the same as production requests.

Private and local IP addresses

A sandbox environment accepts a private or local address in the context.ip parameter. A production environment rejects it with an HTTP 422 response and the error type invalid_parameters, because a private address gives no location, no network reputation, and no useful aggregation.

Addresses that a sandbox environment accepts and a production environment rejects:

A private address in production is a sign that the true client IP is lost behind a proxy or a load balancer. In that case, read the client IP from a header such as X-Forwarded-For.

Data retention

Event retention follows the plan, not the environment type. A sandbox environment keeps events for the same number of days as a production environment on the same plan.