New

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

Migrating from legacy APIs

A guide on how to migrate to the new Risk and Filter APIs for customers who signed up before June 3, 2021.

Introduction

If you signed up before June 3, 2021, you’re likely using the /v1/authenticate and /v1/track endpoints to assess user risk in your application. On June 3, 2021, we launched a new set of endpoints, and we’ll eventually deprecate the old ones. That said, the /v1/authenticate endpoint will be around for the foreseeable future and there hasn’t been a deprecation date set.

The main difference is that the new endpoints use an updated version of our risk engine, which brings a number of improvements mainly related to bot detection. As for the rest of the updates, they are mostly cosmetic in nature, but we’d recommend migrating to new endpoints below, as feature sets will diverge in the future. If you wish to upgrade your account to the 2021-06-03 version, please contact support@castle.io.

  • /v1/risk – The equivalent of calling /v1/authenticate with user_id. See the product page.
  • /v1/filter – The equivalent of calling /v1/authenticate without user_id. See the product page.
  • /v1/log – The equivalent of calling /v1/track but with no risk score or signals generated. Nor will the event be mapped to a device, despite appearing in the user’s timeline.

Updates to the request payload

The new APIs will return an error when the request_token (previously client_id) is missing or invalid.
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 X.X of the client SDKs. Will generate a request error when invalid.
user_iduser.idid now part of the user object
user_traitsuser.traitstraits now part of the user object
user_traits.emailuser.emailemail no longer part of the user_traits object
user_traits.nameuser.namename no longer part of the user_traits object
user_traits.registered_atuser.registered_atregistered_at no longer part of the user_traits object

Updates to the response payload

Old formatNew formatComment
device_tokendevice.token
actionpolicy.action