Documentation
Log inSign up

User Devices API

Suggest Edits

Prerequisites

You must already be sending authenticated events to Castle in order to use the /users/{user_id}/devices endpoint. Examples of these types of events include:

It is recommended that you have already automated the account recovery process before creating dependencies on the user devices API, because using the report function of this API will initiate $incident.confirmed webhooks and restrict associated devices from accessing user accounts. If the Automate Account Recovery tutorial has already been completed, these side effects of the report function will be handled by your automated account recovery processes.

Overview

In order to support your end users, your support team may occasionally want to manually approve or report a device.

Approving a device on a user’s account will set that device’s risk score to 0, marking it as a trusted device and ensuring the end user can access their account with that device without any further challenges or denials being issued by Castle’s default policies.

Reporting a device on a user’s account will set that device’s risk score to 100 and will trigger an $incident.confirmed webhook on that user’s account. Assuming you have already integrated Castle with the login endpoint, reporting a device ensures it will be denied access to the user’s account and the user will be notified and directed to reset their password.

1566

This is an example device management tool that you can build with the user devices API

User device management

Important: This guide is intended for a Device Management Tool that will be used by your internal administrators and support teams. If you want to build a Device Management Tool that will be displayed and used by your end users, please follow the guide for end user feedback.

Step 1. Listing all devices for a user

Example request

In order to fetch a list of devices that have accessed a user's account, call Castle's /users endpoint as such:

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

The cid query param can optionally be used to identify the device that matches a request_token value from your front-end integration. If there is a match, the matching device will have the property is_current_device: true. Example Request:

curl https://api.castle.io/v1/users/{user_id}/devices?cid={client_id} \
  -X GET \
  -u ":YOUR-API-SECRET" \

Example response

{
  "total_count": 1,
  "data": [
    {
      "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6IlAycFQxVXJYZmlJV1ZXcmlCbUdUQ2YxSElabnciLCJxdWFsaWZpZXIiOiJBUUlEQ2pFeE9UTXpPVGc1T1RFIiwiYW5vbnltb3VzIjpmYWxzZSwidmVyc2lvbiI6MC4zfQ.x2gKIzKz11jfN9iXt1XEl45nt8mxpvDmOQ8nMnIJ88E",
      "created_at": "2021-03-29T19:54:47.958Z",
      "last_seen_at": "2021-03-29T19:54:47.549Z",
      "user_id": "6eb07f2b-5401-432d-858e-18d9e35462b3",
      "approved_at": null,
      "escalated_at": null,
      "mitigated_at": null,
      "context": {
        "ip": "188.216.76.142",
        "location": {
          "country_code": "IT",
          "country": "Italy",
          "region": "Lombardy",
          "region_code": "25",
          "city": "Milan",
          "lat": 45.505,
          "lon": 9.2199
        },
        "user_agent": {
          "raw": "Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/6.0; .NET CLR 1.5.73275.9)/44.911",
          "browser": "IE",
          "version": "10.0",
          "os": "Windows 7",
          "mobile": false,
          "platform": "Windows 7",
          "device": "Unknown",
          "family": "IE"
        },
        "properties": {},
        "type": "desktop"
      },
      "is_current_device": false
    }
  ]
}

Using the response

You can use the location, User-Agent information, and timestamps to create a comprehensive view of a users' devices. The screenshot in the Overview section above was built using the response from this endpoint.

Step 2. Feedback buttons

You'll notice that the GET /users/{userId}/devices request returns device objects that each have a token. This token is similar to the device.token returned from inline API calls, but it is not the same. You should not try to match this token or use it in any other way except for Castle API calls.

Using the token of a device from the result of Step 1, you can incorporate feedback buttons in your device management interface. The available device management options are Approve and Report. Once a device has received feedback, there is no way to "reset" the risk score. The risk score can only be overwritten by additional feedback (meaning that once a device is "approved" or "reported", the risk score will only ever be 0 or 100 depending on the most recent feedback).

Approve a device

You may build an "Approve" button into your device management UI. Upon clicking Approve, send a PUT request to Castle's devices endpoint as such:

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

Important: By approving a device, you are confirming that this device was used by the account owner. The device’s risk score will be pegged to 0, and it will be considered a safe device for this user. Only do this if you have confidently confirmed that this device is in use by the true account owner.

Report a device

You may build a "Report" button into your device management UI. Upon clicking Report, send a PUT request to Castle's devices endpoint as such:

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

Important: By reporting a device, you are confirming a compromise on this user’s account and pegging the device to a risk score of 100. It will result in an $incident.confirmed event and webhook event being triggered for this user. Therefore, assuming you have already completed the guide Automate Account Recovery, a Password Reset email will be automatically sent to this user.

Retrieve a device

You can fetch a single device to check its state, among other things:

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

The following fields denote the current state:

  • approved_at – if timestamp is set, the device was approved at that time
  • escalated_at – if timestamp is set, the device was reported at that time
  • mitigated_at – if timestamp is set, the device was archived as part of a ATO recovery flow

Updated almost 2 years ago