Migrating from legacy APIs

A guide on how to migrate to the new Risk and Filter APIs.

Introduction

On June 3, 2021, we launched a new set of API endpoints as well as 2.0 versions of our client-side SDKs. The new endpoints run a more comprehensive fraud detection model, as opposed to the legacy model that was mainly tuned to detect account takeovers. Additionally, the new client-side SDKs implements more sophisticated device fingerprinting and in-app behavioral analysis that can be used to better identify unique devices, as well as any device tampering or anomalous user interactions.

Migration guide

Phase 1: Client-side

Update the client-side SDKs to the 2.0 version or later. The main difference is that the new server-side APIs will use the new Request Token, as opposed to the old Client ID.

The new request_token string needs to be generated in the client right before any backend request that's going to be sent to Castle since it expires after 120 seconds. It will need to be present on 100% of your requests so you should make sure this is verified before proceed to the next step. Any missing request tokens will result in an API validation error.

Force your users to do an update of their apps next time they open the app so that all users will have the 2.0 of the Castle SDKs. If you're unable to do a force update, you'll need to make sure that either you don't send old requests to the Risk API since they'll trigger an error, alternatively you use the Log API to log these events to the user timeline without performing any risk scoring.

📘

Note that you can send the new request token to the legacy endpoints as client_id while you're going through the client-side upgrade.

Phase 2: Upgrade your environment

Contact [email protected] and we will help you validate that your new client-side request tokens are forwarded to our API, and we'll then migrate your environment to the new risk model.

Phase 3: Server-side

Once you've validated that 100% of your requests now contain the new Request Token as opposed to the Client ID, you're ready to switch over to the new APIs:

  • /v1/risk -- Similar to calling /v1/authenticate with user_id. See the API reference.
  • /v1/filter -- Similar to calling /v1/authenticate without user_id. See the API reference.
  • /v1/log -- Similar to calling /v1/track but with no risk score or signals generated. You will likely send your failed logins and challenge events to this endpoint. See the API reference.

❗️

The new APIs will return an error when the request_token (previously client_id) is missing or invalid, so it's important that you validate that it's present on 100% of your requests before migrating.

Updates to the request payload

Old formatNew formatComment
eventeventFormat changed from $login.succeeded to $login
N/AstatusThe last part of the old event, e.g. $succeeded
context.client_idrequest_tokenRequires version 2.0 of the client SDKs. Will generate a request error when invalid.
user_iduser.idAttribute moved
user_traitsuser.traitsObject moved
user_traits.emailuser.emailAttribute moved
user_traits.nameuser.nameAttribute moved
user_traits.registered_atuser.registered_atAttribute moved

Updates to the response payload

Old formatNew formatComment
device_tokendevice.token
actionpolicy.action