Account Takeover Integration

Reclaiming Accounts

This page explains how to tell us an account has been resecured after an account takeover.

In cases where an account is reclaimed by the legitimate owner you need to notify us that the account has been secured. Secured means that the password has been reset and any tokens have been revoked, ensuring that attackers no longer have access to the account.

Reclaiming an account after it has been resecured is important, otherwise we may block the legitimate owner from accessing the account.

Customer accounts should be reclaimed if:

  • A login was blocked by Ravelin because of a suspected account takeover attempt, and you have forced the password to be reset.
  • A customer experiences and reports account takeover, and the account has now been secured.
  • An internal investigation identifies account takeover, and results in the password being reset.

We strongly recommend only notifying us about reclaimed customer accounts when you are certain that the fraudster has lost access to the account. A reclaim on a customer account is taken into consideration when generating account takeover recommendations, and for a short time, new logins are likely to be permitted for the customer, even if they look suspicious.

If you support social login, you may need to consider unlinking social accounts as part of a reclaim. This is in the event that a fraudster logs in and links a social account which can then be used to continue accessing the account.

To notify us that customer accounts have been reclaimed, send a request to our Reclaim Endpoint.

An example request is shown below:

POST https://api.ravelin.com/v2/reclaim HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customers": [
    {
      "customerId": "example-customer-1",
      "method": "PasswordReset",
      "reportedBy": "RAVELIN",
      "atoEvents": [
        {
          "loginId": "42bd8af9-1ac2-7b2c-cd6a-a6a33c723510"
        }
      ]
    }
  ]
}

A reclaim request can contain up to 1000 customer accounts. If more that 1000 customer accounts are in the request, we will respond with an error.

We will respond with a message stating the number of accounts processed. This will always be the same as the amount provided in the request. See the Reclaim Endpoint API Reference for the format of the response.

An example response is shown below:

{
  "status": 200,
  "message": "1 customer accounts reclaimed successfully"
}

Next steps

Test your account takeover integration

Feedback