Castle API Reference

Introduction

The Castle API is REST-based: it is designed to have predictable urls and uses built-in HTTP features like HTTP Basic Authentication, Response Codes and HTTP Verbs. All requests, including errors, return JSON. The API expects JSON for all POST and PUT requests.

The REST API forms the platform which our libraries are built on. We don't recommend that you build an app using the REST API exclusively – you will probably want to use one of our libraries for that.

However, if you need to reference the way something works on a lower level, or if you're curious about how the libraries interact with the platform itself, this reference has the details.

API Endpoint

api.castle.io/v1

Authentication

You authenticate to the Castle API by providing your API Secret in the request. The API Secret is random string which gives you full read and write access to your Castle account, so be sure to keep it hidden.

Authentication to the API occurs via HTTP Basic Auth. Provide your API Secret as the basic auth password. You do not need to provide a username.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

Example

curl -s https://api.castle.io/v1 \
     -u ":HCL1SVj3nw4KmL7YpzpivxNyDsUYjbgq"

Note the absence of a basic auth username, and remember the colon!

Errors

Castle uses standard HTTP response codes to indicate whether a request was successful or not. All errors return a JSON object describing the error.

Error object

type
String
Type of error
message
String
Human readable text describing the error that occurred

Example response

{
  "type": "invalid_parameters",
  "message": "One or more parameters are invalid"
}

Summary of response codes

Code Type
400 bad_request
400 missing_headers
400 invalid_header_value
401 unauthorized
403 forbidden
404 not_found
404 route_not_found
422 invalid_parameters
500 server_error
503 service_unavailable

Request context

When calling API:s from your backend, the IP and user agent headers will reflect your server configuration rather than the logged in user resulting in incorrect profiling. Therefore you will need to manually provide this information with the following headers:

  • X-Castle-Client-Id – The cookie set by Castle.js, available as __cid in your cookie store.
  • X-Castle-Ip – The user's IP address, e.g. 87.12.111.29
  • X-Castle-Headers - The available headers from the original request initited by the user's browser, 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"}

Example

curl -X POST \
     -H "X-Castle-Client-Id: a97b492d-dcc3-4fc1-87d6-65682955afa5"
     -H "X-Castle-Ip: 87.12.111.29" \
     -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\"}" \
     -u ":YOUR-API-SECRET" \
     https://api.castle.io/v1/users/2412

Client libraries should send these headers on every API call made on behalf of a logged in user.

Track

Track an event

Track lets you record security-related actions your users perform. Events are processed asynchronously to return as quickly as possible.

Arguments

name
String
Required.
timestamp
[String, Time]

Timestamp of the event

created_at
[String, Time]

Timestamp of the event (DEPRECATED)

sent_at
String
received_at
String
user_id
String

Id of the logged in user

properties
Hash

Optional parameter for recording additional information connected to the event.

traits
Hash

Optional parameter for recording additional information about the user like email or name.

context
Hash

Optional request context.

Response codes

Code Description
204 The event was successfully created

Definition

POST /v1/track(.json)

Authenticate

The authenticate object

Name Description
action
Enum
user_id
String

Authenticate an action

Authenticate is processed synchronous and returns returns an action of the types allow, challenge or deny.

Arguments

user_id
String
Required.

Id of the logged in user

name
String
timestamp
[String, Time]

Timestamp of the event

created_at
[String, Time]

Timestamp of the event (DEPRECATED)

sent_at
String
received_at
String
event
String
properties
Hash

Optional parameter for recording additional information connected to the event.

traits
Hash

Optional parameter for recording additional information connected to the user.

context
Hash

Optional request context.

Response codes

Code Description
201 The event was successfully created

Definition

POST /v1/authenticate(.json)

Example response

{
  "action": "approve",
  "user_id": "12345"
}

Identify

Identify a user

User updates are processed asynchronously to return as quickly as possible.

Arguments

user_id
String
Required.
traits
Hash

Optional parameter for recording additional information about the user like email or name.

context
Hash

Optional request context.

timestamp
[String, Time]

Timestamp of the event

created_at
[String, Time]

Timestamp of the event (DEPRECATED)

sent_at
String
received_at
String

Definition

POST /v1/identify(.json)

Review

The review object

Name Description
user_id
String
Id of the user
context
String
Request context to review

Retrieve a review object

Reviews lets you fetch the context for a user to review anomalous account activity.

Definition

GET /v1/reviews/{review_id}(.json)

Example response

{
  "user_id": "joH8NAVsYwRW4yBvPddS6TzydMmTjuzF",
  "context": {
    "ip": "69.181.35.4",
    "user_agent": {
      "raw": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) ...",
      "browser": "Chrome",
      "mobile": false,
      "os": "Mac OS X 10.9.5",
      "version": "42.0.2311"
    },
    "location": {
      "country": "United States",
      "country_code": "US",
      "region": "California",
      "region_code": "CA",
      "city": "San Francisco",
      "lon": -55.654325,
      "lat": 13.043243
    }
  }
}