API reference

Details about the Castle API endpoints

Summary

All endpoints are protected by basic authentication. This means setting an Authorization header with the value Basic :<<SECRET>> where <<SECRET>> is your API secret encoded with Base64. If the authorization header is missing or incorrect, the API will respond with 401.

The API only understands JSON requests and requires the Content-Type header to be set to application/json in requests with a body, such as POST or PUT.

Castle supports TLS version 1.1 and higher.


Supported events

For a list of supported events, see our Events Reference.

Failed requests

Successful response codes and payloads are documented per each endpoint, but errors are generalized into these codes: 401, 403, 422, 500.

Error CodeDescription
401 UnauthorizedYou are missing the Authorization header, or the API secret is missing or incorrect.
403 ForbiddenThe request is rejected because the service is not enabled for this account.
422 Unprocessable EntityThe request body is unprocessable by the API. Make sure it conforms to the specified format for the endpoint.
500 Internal Server ErrorThere’s an issue on our end.

Authenticate

/v1/authenticate

Send an event to Castle’s API for risk evaluation, and get a recommended action back. The most obvious use of this is for login requests, where the API can indicate malicious and questionable circumstances, but it can be used for any event. Note that the request payload schema matches that of /v1/track. See the List of Recognized Events for officially supported events and statuses. Send status: $succeeded when your application logic is prepared to send a “success” response to the user, but you want to evaluate risk first (i.e. after email/password validation at login). Send status: null when your application logic has not yet evaluated the event (i.e. if you’ve just received a login or registration request, and you want to evaluate risk outside the context of a specific user_id).

Note that many example cURL requests in our documentation show user_agent, and eliminate headers, in the /authenticate or /track request body. We recommend sending a headers object that includes headers["User-Agent"]. If the headers object is unavailable, then replacing it with user_agent will meet the minimum requirements.

Method : POST

Request payload example

{
  "event": "$login.succeeded",
  "user_id": "591ba993-c4bd-46c3-b3c0-5178aefa5a0b",
  "user_traits": {
    "email": "Rhea.Franecki@example.org",
    "registered_at": "2019-10-21T06:05:50.000Z"
  },
  "context": {
    "client_id": "7c62540a-1808-4ee6-85b9-c8e1b02661fd",
    "ip": "246.106.111.94",
    "headers": {
      "Accept": "application/x-research-info-systems",
      "Accept-Encoding": "sdkd",
      "Cache-Control": "max-age=680",
      "Content-Type": "multipart/form-data",
      "Content-Length": "157",
      "Connection": "close",
      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_9 rv:2.0; MK) AppleWebKit/538.0.2 (KHTML, like Gecko) Version/5.0.0 Safari/538.0.2/765.251",
      "Accept-Charset": "utf-8",
      "Accept-Language": "sq",
      "Authorization": "eJEgNHfJBmXq1C1",
      "Cookie": "bandwidth=0af87174-37b4-4adc-a1a6-eb7c7e4ca440",
      "From": "Titus57@example.net",
      "Host": "http://erna.com",
      "If-Match": "b7081d66-7666-4574-b5ef-d6e047d69200",
      "If-Modified-Since": "Thu Mar 04 2021 17:41:23 GMT-0800 (Pacific Standard Time)",
      "If-None-Match": "5d7af4f5-07bc-4fec-b7c9-1fb3a235c762",
      "If-Range": "f6bd9146-5eb5-4c19-9776-5e91bb35a3ad",
      "If-Unmodified-Since": "Fri Mar 05 2021 04:24:23 GMT-0800 (Pacific Standard Time)",
      "Max-Forwards": "633",
      "Referer": "http://ignacio.net"
    },
    "library": { "name": "castle-postman", "version": "0.1.0" }
  }
}

Successful response

Code : 201 CREATED

{
  "action": "deny",
  "user_id": "591ba993-c4bd-46c3-b3c0-5178aefa5a0b",
  "device_token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6InJtUllyb0haZFZuZFcyR1p6VzdPLWdSSkt1STciLCJxdWFsaWZpZXIiOiJBUUlDQ2pFeU1qYzFORE0wTkRVIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ._hCtxD77NRQhmPtmB5CP2EE1vb8KZa9j6hY1ee-SXMw",
  "risk": 0.93,
  "signals": {
    "bot_behavior": {},
    "proxy_ip": {},
    "disposable_email": {},
    "spoofed_device": {},
    "multiple_accounts_per_device": {}
  }
}

Possible values of action are allow, challenge, deny.


Track

/v1/track

Track an event from your system with the API. This endpoint doesn’t provide a response body and it is designed for use in a non-blocking manner. A 204 response means that the request was received by Castle’s API. The Castle Debugger must be used to check and debug any malformed requests.

Method : POST

Request payload

Matches that of /v1/authenticate.

Successful response

Code : 204 NO CONTENT

Provides no response body.


Devices

/v1/users/{user_id}/devices

Using a user ID, get all devices associated with that user.

Optional: Provide the cid query param with a client_id (also known as the fingerprint) value from Castle.js or a Castle Mobile SDK in order to see is_current_device: true when cid matches a known device fingerprint in the list of devices. Example: /v1/users/{user_id}/devices?cid={client_id}

Method : GET

Successful response

Code : 200 OK

{
  "total_count": 2,
  "data": [
    {
      "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6IlAybGJnOF9VZG5TVFZtSzBnMkRlT2pSRUtjOTEiLCJxdWFsaWZpZXIiOiJBUUlEQ2pFeE5ETTFOekUxTXpBIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ.cM_SgKgLMCRKAhkWJK5YxS3nXP5u47vEnmAD_vjLlI8",
      "created_at": "2021-02-24T21:39:32.729Z",
      "last_seen_at": "2021-02-24T21:39:32.501Z",
      "user_id": "f2dbec55-95f3-4d7a-8d28-f73799f892ed",
      "approved_at": null,
      "escalated_at": null,
      "mitigated_at": null,
      "context": {
        "ip": "180.69.216.170",
        "location": {
          "country_code": "KR",
          "country": "South Korea",
          "region": "Seoul",
          "region_code": "11",
          "city": "Songpa-dong",
          "lat": 37.5079,
          "lon": 127.1177
        },
        "user_agent": {
          "raw": "Mozilla/5.0 (Windows; U; Windows NT 6.0) AppleWebKit/535.1.2 (KHTML, like Gecko) Chrome/24.0.832.0 Safari/535.1.2/807.831",
          "browser": "Chrome",
          "version": "24.0.832",
          "os": "Windows Vista",
          "mobile": false,
          "platform": "Windows Vista",
          "device": "Unknown",
          "family": "Chrome"
        },
        "properties": {},
        "type": "desktop"
      },
      "is_current_device": false
    },
    {
      "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6IlAybGJoVUxVZG5JZVZtS3lEbURlUExsRUtjbjQiLCJxdWFsaWZpZXIiOiJBUUlEQ2pFeE5ETTFOekV4TkRNIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ.YEcRWGpva0B5xLeF9EDfCxBILhVUBh-5ODEuCjGmbno",
      "created_at": "2021-02-24T21:39:12.826Z",
      "last_seen_at": "2021-02-24T21:39:12.007Z",
      "user_id": "f2dbec55-95f3-4d7a-8d28-f73799f892ed",
      "approved_at": null,
      "escalated_at": null,
      "mitigated_at": null,
      "context": {
        "ip": "106.149.150.49",
        "location": {
          "country_code": "JP",
          "country": "Japan",
          "region": null,
          "region_code": null,
          "city": null,
          "lat": 35.6897,
          "lon": 139.6895
        },
        "user_agent": {
          "raw": "Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/5.0; .NET CLR 1.8.61225.4)/730.192",
          "browser": "IE",
          "version": "9.0",
          "os": "Windows 7",
          "mobile": false,
          "platform": "Windows 7",
          "device": "Unknown",
          "family": "IE"
        },
        "properties": {},
        "type": "desktop"
      },
      "is_current_device": false
    }
  ]
}

/v1/devices/:device_token

Using a device token, get information about that device.

Method : GET

curl https://api.castle.io/v1/devices/{device_token} \
  -X GET \
  -u ":YOUR-API-SECRET" \

Successful response

Code: 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6IlAybGJnOF9VZG5TVFZtSzBnMkRlT2pSRUtjOTEiLCJxdWFsaWZpZXIiOiJBUUlEQ2pFeE5ETTFOekUxTXpBIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ.cM_SgKgLMCRKAhkWJK5YxS3nXP5u47vEnmAD_vjLlI8",
  "created_at": "2021-02-24T21:39:32.729Z",
  "last_seen_at": "2021-02-24T21:39:32.501Z",
  "user_id": "f2dbec55-95f3-4d7a-8d28-f73799f892ed",
  "approved_at": null,
  "escalated_at": null,
  "mitigated_at": null,
  "context": {
    "ip": "180.69.216.170",
    "location": {
      "country_code": "KR",
      "country": "South Korea",
      "region": "Seoul",
      "region_code": "11",
      "city": "Songpa-dong",
      "lat": 37.5079,
      "lon": 127.1177
    },
    "user_agent": {
      "raw": "Mozilla/5.0 (Windows; U; Windows NT 6.0) AppleWebKit/535.1.2 (KHTML, like Gecko) Chrome/24.0.832.0 Safari/535.1.2/807.831",
      "browser": "Chrome",
      "version": "24.0.832",
      "os": "Windows Vista",
      "mobile": false,
      "platform": "Windows Vista",
      "device": "Unknown",
      "family": "Chrome"
    },
    "properties": {},
    "type": "desktop"
  },
  "is_current_device": false
}

Device token

/v1/devices/:device_token/approve

Approve a device using its device token.

Method : PUT

Successful response

Code : 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6IlAybGJnOF9VZG5TVFZtSzBnMkRlT2pSRUtjOTEiLCJxdWFsaWZpZXIiOiJBUUlEQ2pFeE5ETTFOekUxTXpBIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ.cM_SgKgLMCRKAhkWJK5YxS3nXP5u47vEnmAD_vjLlI8",
  "created_at": "2021-02-24T21:39:32.729Z",
  "last_seen_at": "2021-02-24T21:39:32.501Z",
  "user_id": "f2dbec55-95f3-4d7a-8d28-f73799f892ed",
  "approved_at": "2021-02-24T22:53:38.785Z",
  "escalated_at": null,
  "mitigated_at": null,
  "context": {
    "ip": "180.69.216.170",
    "location": {
      "country_code": "KR",
      "country": "South Korea",
      "region": "Seoul",
      "region_code": "11",
      "city": "Songpa-dong",
      "lat": 37.5079,
      "lon": 127.1177
    },
    "user_agent": {
      "raw": "Mozilla/5.0 (Windows; U; Windows NT 6.0) AppleWebKit/535.1.2 (KHTML, like Gecko) Chrome/24.0.832.0 Safari/535.1.2/807.831",
      "browser": "Chrome",
      "version": "24.0.832",
      "os": "Windows Vista",
      "mobile": false,
      "platform": "Windows Vista",
      "device": "Unknown",
      "family": "Chrome"
    },
    "properties": {},
    "type": "desktop"
  },
  "is_current_device": false
}

/v1/devices/:device_token/report

Report a device using its device token.

Method : PUT

Successful response

Code : 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6IlAybGJnOF9VZG5TVFZtSzBnMkRlT2pSRUtjOTEiLCJxdWFsaWZpZXIiOiJBUUlEQ2pFeE5ETTFOekUxTXpBIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ.cM_SgKgLMCRKAhkWJK5YxS3nXP5u47vEnmAD_vjLlI8",
  "created_at": "2021-02-24T21:39:32.729Z",
  "last_seen_at": "2021-02-24T21:39:32.501Z",
  "user_id": "f2dbec55-95f3-4d7a-8d28-f73799f892ed",
  "approved_at": null,
  "escalated_at": "2021-02-24T22:54:07.647Z",
  "mitigated_at": null,
  "context": {
    "ip": "180.69.216.170",
    "location": {
      "country_code": "KR",
      "country": "South Korea",
      "region": "Seoul",
      "region_code": "11",
      "city": "Songpa-dong",
      "lat": 37.5079,
      "lon": 127.1177
    },
    "user_agent": {
      "raw": "Mozilla/5.0 (Windows; U; Windows NT 6.0) AppleWebKit/535.1.2 (KHTML, like Gecko) Chrome/24.0.832.0 Safari/535.1.2/807.831",
      "browser": "Chrome",
      "version": "24.0.832",
      "os": "Windows Vista",
      "mobile": false,
      "platform": "Windows Vista",
      "device": "Unknown",
      "family": "Chrome"
    },
    "properties": {},
    "type": "desktop"
  },
  "is_current_device": false
}

Impersonate

/v1/impersonate

Inform Castle that some part of your support team is impersonating a user, to prevent us from tracking it as real activity. . Impersonation mode relies on the client_id value remaining consistent for all impersonated events.

Impersonation mode assumes that a single impersonator performs the impersonation on one user account at a time. One active impersonation will be recognized per client_id.

Method : POST

Request payload example

Notify Castle of Impersonation: POST /v1/impersonate

{
  "user_id": "1234",
  "impersonator": "optional_admin_id_or_email",
  "context": {
    "client_id": "a97b492d-dcc3-4fc1-87d6-65682955afa5",
    "ip": "37.46.187.90",
    "user_agent": "Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko"
  }
}

Successful response

Code : 201 Created

{
  "success": true
}