humble.md

Minimum Castle Integration

Frontend tracking

The Castle JavaScript, Castle.js, automatically captures device properties, location data and browsing habits, and then sets a tracking cookie to be read out during the backend tracking. This lets our risk engine correlate data between client and server to ensure consistency.

There are two ways of integrating Castle.js on your site. You either pull it from our CDN, or if you prefer serving it from your host then fetch it from npm.

Backend tracking

Use the /v1/track endpoint to track events that might be relevant in identifying account takeovers. We have a list of standard events that all have special meaning to our risk engine, but any custom event name may be used.

curl https://api.castle.io/v1/track \
  -u ":YOUR-API-SECRET" \
  -H "Content-Type: application/json" \
  -H "X-Castle-Cookie-Id: a97b492d-dcc3-4fc1-87d6-65682955afa5" \
  -H "X-Castle-Ip: 37.46.187.90" \
  -H "X-Castle-Headers: {\"User-Agent\": \"Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko\", \"Accept\": \"text/html\", \"Accept-Language\": \"en-us,en;q=0.5\"}" \
  \
  -d '{"name": "$login.succeeded", "user_id": "1234", "details": {"my_important_value": "52"}}'

All of the specified headers are required, including the following that are specific to Castle:

• X-Castle-Cookie-Id – The cookie set by Castle.js, available as __cid in your browser's cookie store.
• X-Castle-Ip – The user's IP address, e.g. 87.12.111.29
• X-Castle-Headers - All headers except Cookie from the incoming HTTP request, encoded as a JSON string, e.g. {\"User-Agent\":\"Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko\",\"Accept\":\"text/html\",\"Accept-Language\":\"en-us,en;q=0.5\"}. See the Ruby library for an example.

Troubleshooting: If you see a "Missing cookie" signal being generated in the user timeline that means you have probably got the X-Castle-Cookie-Id wrong (or you actually removed the cookie from your browser!)

Event types to track

• $login.succeeded: Record when a user logs in.
• $login.failed: Record when a user attempts to log in and fails.
• $challenge.requested: Record when a user is prompted with out-of-band authentication, such as two-factor authentication.
• $challenge.succeeded: Record when out-of-band authentication was successful.
• $challenge.failed: Record when out-of-band authentication failed.