New

If you signed up before June 3, 2021, see the migration guide to learn about the recent API changes.

APIs

Details about the Castle API endpoints

Introduction

Just getting started? Check out our quick start guide

Castle APIs uses standard HTTP response codes, authentication and verbs. JSON is used as data exchange format, both for parsing incoming request bodies, and in the returned response. This means that the Content-Type header should to be set to application/json in requests with a body, such as POST or PUT.

All API requests must be made over HTTPS. Non-HTTPS calls will fail and the TLS version needs to be 1.1 or higher.

Authentication

API keys are used to authenticate all Castle APIs. In the Castle Dashboard you can view and manage your API keys.

Castle API keys are secret. Make sure to not share them in publicly accessible areas such as GitHub or client-side code.

All endpoints are authenticated via HTTP Basic Auth, using password and no username. This means setting an Authorization header with a leading “:”, eg. Basic :<<SECRET>>, where <<SECRET>> is your API key encoded with Base64. If the authorization header is missing or incorrect, the API will respond with 401.


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.

Filter

Used to block bots and bad traffic early in the request chain, typically at registration. Read more in the Prevent Fake Accounts section. See the List of Recognized Events for supported events.

At minimum the User-Agent key is required in the headers object.

/v1/filter

Method : POST

{
  "event": "$registration",
  "user": {
    "email": "Rhea.Franecki@example.org",
  },
  "request_token": "test_lZWva9rsNe3u0_EIc6R8V3t5beV38piPAQbhgREGygYCAo2FRSv1tAQ4-cb6ArKHOWK_zG18hO1uZ8K0LDbNqU9njuhscoLyaj3NyGxyiO0iS4ziIkm-oVom3LEsN9i6InSbuzo-w7ErJqrkYW2CrjA23LEyN92wIkCE82dggvktPtWvMmrl42Bj2uM7Zdn2AQGXC6qGTIECRlwaAgZcgcAGeX4",
  "context": {
    "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",
      "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)",
      "Referer": "http://ignacio.net"
    }
  }
}

Successful response

Code : 201 CREATED

{
  "policy": {
    "action": "deny",
    "name": "block bots",
    "id": "e14c5a8d-c682-4a22-bbca-04fa6b98ad0c",
    "revision": "b5cf794e-88c0-426e-8276-037ba1e7ceca"
  },
  "risk": 0.93,
  "signals": {
    "bot_behavior": {},
    "proxy_ip": {},
    "disposable_email": {},
    "spoofed_device": {},
    "multiple_accounts_per_device": {}
  }
}

Risk

/v1/risk

Used to request a risk evaluation from Castle’s API. The most obvious use of this is for login requests, where the API can indicate malicious and questionable circumstances. Read more in the Prevent Account Takeovers section. See the List of Recognized Events for supported events.

Method : POST

Request payload example

The payload requirements for /v1/risk are identical to /v1/filter except for also requiring the user object.

{
  "event": "$login",
  "user": {
    "id": "591ba993-c4bd-46c3-b3c0-5178aefa5a0b",
    "email": "Rhea.Franecki@example.org",
    "registered_at": "2019-10-21T06:05:50.000Z"
  },
  "request_token": "test_lZWva9rsNe3u0_EIc6R8V3t5beV38piPAQbhgREGygYCAo2FRSv1tAQ4-cb6ArKHOWK_zG18hO1uZ8K0LDbNqU9njuhscoLyaj3NyGxyiO0iS4ziIkm-oVom3LEsN9i6InSbuzo-w7ErJqrkYW2CrjA23LEyN92wIkCE82dggvktPtWvMmrl42Bj2uM7Zdn2AQGXC6qGTIECRlwaAgZcgcAGeX4",
  "context": {
    "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",
      "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)",
      "Referer": "http://ignacio.net"
    }
  }
}

Successful response

Code : 201 CREATED

{
  "device": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6InJtUllyb0haZFZuZFcyR1p6VzdPLWdSSkt1STciLCJxdWFsaWZpZXIiOiJBUUlDQ2pFeU1qYzFORE0wTkRVIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ._hCtxD77NRQhmPtmB5CP2EE1vb8KZa9j6hY1ee-SXMw"
  },
  "policy": {
    "action": "deny",
    "name": "block bots",
    "id": "e14c5a8d-c682-4a22-bbca-04fa6b98ad0c",
    "revision": "b5cf794e-88c0-426e-8276-037ba1e7ceca"
  },
  "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.

This endpoint does not return any error status upon a malformed request. Use the Castle Debugger to debug and spot any errors.

Method : POST

Request payload

Matches that of /v1/filter.

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
}