API Reference
Reference for the public Castle API. All requests use HTTPS and JSON for request and response bodies.
Introduction
The Castle API is a standard HTTP API for sending security, fraud, and account activity data to Castle and receiving structured JSON results. It uses standard HTTP response codes, authentication, and verbs.
All API requests must use HTTPS. Non-HTTPS calls fail, and the TLS version must be 1.1 or higher. JSON is used for request and response bodies, so requests with a body, such as POST or PUT , must set Content-Type: application/json.
Rate limits
Castle APIs limit the number of requests. Each request returns the following headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | The maximum number of requests that you can make in the current time window. |
X-RateLimit-Remaining | The number of requests remaining in the current time window. |
X-RateLimit-Reset | The remaining time in seconds until the current time window resets. |
The Risk, Filter, and legacy Authenticate APIs also have a per-user-id rate limit of 6 requests per second and 10 requests per 5 seconds.
Authentication
API keys authenticate Castle APIs. You can view and manage API keys in the Castle Dashboard. Castle API keys are secret, so do not share them in publicly accessible areas such as GitHub or client-side code.
All endpoints use HTTP Basic Auth with your API secret as the password and no username. Set the Authorization header to Basic base64(:API_SECRET) . If the header is missing or incorrect, Castle responds with 401.
| Security scheme type | HTTP |
|---|---|
| HTTP authorization scheme | basic |
Risk Assessment
Lists
Events
Privacy
- Request User Data Deprecated
- Delete User Data Deprecated
- Request User Data
- Delete User Data