thisdata

thisdata-node

thisdata-node is a nodejs client for the ThisData Login Intelligence API (https://thisdata.com).

Setup

Install the latest thisdata-node package from npm

npm install thisdata --save

Create a ThisData client

var ThisData = require('thisdata');
var thisdata = ThisData("YOUR API KEY FROM THISDATA");

Track Events

Use this method to asynchronously track events that happen in your app.

thisdata.track(request, options);

To track login related events, find the point in your code just after a login success, failure or password reset and use the track method to send data to the ThisData API.

thisdata.track(req, {
  verb: thisdata.verbs.LOG_IN,
  user: {
    id: 'john123455',
    name: 'John Titor',
    email: '[e-mail]'
  }
});

Options

ip and user_agent are extracted from req but you can override these value and supply additional fields using options.

{
  verb: 'transfer',
  ip: '0.0.0.0',
  userAgent: 'Firefox, Windows 98',
  user: {
    id: 'john123455',
    name: 'John Titor',
    email: '[e-mail]'
  },
  session: {
    id: 'Optional'
    cookieExpected: true
  },
  device: {
    id: 'mobile-device-id'
  }
}

• user.name - string The full name of the user
• user.email - string - An email address for sending unusual activity alerts to
• user.mobile - E.164 format - An mobile number for sending unusual activity SMS alerts to. e.g. [phone]
• session.id - string - Typically a browser session id but it's up to you
• session.cookieExpected - boolean - Used in combination with ThisData Javascript. Set true if the script is installed
• device.id - string - A unique device identifier. Typically used for tracking mobile devices.

Event Types

We recommend using verb constants thisdata.verbs.LOG_IN but you can use any verb that represents the type of event that you want to track.

For a full list of verbs see http://help.thisdata.com/v1.0/docs/verbs

Verify Identity

Use the Verify method to enable contextual authentication in your app. It accepts the same parameters as the Track event with the exception of the event type/verb.

thisdata.verify(request, options, callback);

Verify will return a risk score between 0->1 which indicates our level confidence that the user is who they say they are.

{ score: 0, risk_level: 'green', triggers: [], messages: [] }

0.0 - low risk/high confidence it's the real user

1.0 - high risk/low confidence it's the real user

thisdata.verify(req, {
  user: {
    id: 'john123455',
    name: 'John Titor',
    email: '[e-mail]'
  }
}, function(err, body){
 
  if(body.score > 0.9){
    // Step up authentication
  }
 
});

Get a list of Events

You can get a list of events enriched with their risk score and location data for use in custom audit logs. See the docs for possible query filters and paging params.

thisdata.getEvents(options, callback);

Get last successful log-in time and location for a user.

thisdata.getEvents({
  user_id: 'john123455',
  limit: 1,
  verbs: ['log-in']
}, function(err, body){
 
  // last login was from
  var loginCity = body.results[0].location.address.city_name;
 
});

Managing custom Rules

You can get, create, update and delete custom rules.

Create a rule

// returns a rule
 
thisdata.rules.create({
  name: "Blacklist all ipv4 addresses",
  description: "Blocks every possible ipv4 address",
  type: "blacklist",
  target: "location.ip",
  filters: ["0.0.0.0/0"]
}, function(err, rule){ });

List all rules

thisdata.rules.list(function(err, rules){ });

Find a single rule

thisdata.rules.get("123456", function(err, rule){
  console.log(rule.id);
})

Update a rule

// id is reqired. Other params are optional
 
thisdata.rules.update({
  id: "123456",
  filters: ["0.0.0.0/0",""]
}, function(err, rule){ });

Delete a rule

// returns deleted as bool
thisdata.rules.delete("123456", function(err, deleted){ })

Webhooks

You should validate incoming webhooks to make sure they're from ThisData. To do this you will enter a secret string in the settings area of your ThisData account and then use that same secret to validate the webhook signature that we send in the X-Signature header.

var valid = thisdata.validateWebhook('your shared secret', 'X-Signature value', 'request body');

For more information about types of webhooks you can receive see http://help.thisdata.com/docs/webhooks

API Documentation

API Documentation is available at http://help.thisdata.com/docs/apiv1events.

Test

Run the unit tests

npm test

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/thisdata/thisdata-node