NodeJS client for the ThisData API
JavaScript
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib added support for rules May 26, 2017
test added support for rules May 26, 2017
.gitignore Initial commit May 6, 2016
.travis.yml remove node 0.8, 0.6 testing May 27, 2016
LICENSE licensed it May 26, 2016
README.md added support for rules May 26, 2017
index.js make it work with npm May 27, 2016
package.json version bump May 26, 2017

README.md

thisdata-node Build Status

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: 'john+titor@thisdata.com'
  }
});

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: 'john+titor@thisdata.com'
  },
  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. +15555555555
  • 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: 'john+titor@thisdata.com'
  }
}, 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