Edit

SDK Guide

Here you can find all the information that you need to get started using SecureNative SDK:

Installation

    npm install @securenative/sdk
// When using Maven, add the following dependency to your `pom.xml` file:

<dependency>
    <groupId>com.securenative.java</groupId>
    <artifactId>sdk-base</artifactId>
    <version>0.2.2</version>
</dependency>


// Gradle:

// compile group: 'com.securenative.java', name: 'sdk-base', version: 'LATEST'
pip install securenative
Install the `SecureNative.Sdk` nuget.
 
//Command line:
nuget install SecureNative.Sdk

//Packet Manager Console

 install-package SecureNative.Sdk

//Visual Studio

1. Go to Tools -> Package Manager -> Manage NuGet Packages for Solution...
2. Click the Browse tab and search for `SecureNative.Sdk`
3. Click the `SecureNative.Sdk` package in the search results, select version and what projects to apply it to on the right side, and click Install
# Add this line to your application's Gemfile:

gem 'securenative'

# And then execute:

$ bundle

# Or install it yourself as:

$ gem install securenative

$ composer require securenative/securenative-php

Initialize the SDK

Go to the settings page of your SecureNative account and find your API KEY

Initialize using API KEY

import { SecureNative, EventTypes } from "@securenative/sdk";
or;
const { SecureNative, EventTypes } = require("@securenative/sdk"); // if your using ES5
//Option 1: Initialize via Config file
SecureNative can automatically load your config from securenative.properties file or from the file that is specified in your SECURENATIVE_CONFIG_FILE env variable:

SecureNative secureNative =  SecureNative.init();
//Option 2: Initialize via API Key
SecureNative secureNative =  SecureNative.init("YOUR_API_KEY");
from securenative.securenative import SecureNative


secureative =  SecureNative.init()
var apiKey = "API_KEY";
var sn = new SecureNative.SDK.SecureNative(apiKey, new SecureNative.SDK.Models.SecureNativeOptions());
require 'securenative'

# Do some cool stuff here
# ...
# ...
 
begin
  SecureNative.init('YOUR_API_KEY') # Should be called before any other call to securenative
rescue SecureNativeSDKException => e
  # Do some error handling
end
require_once __DIR__ . '/vendor/autoload.php';

use SecureNative\sdk\SecureNative;
use SecureNative\sdk\SecureNativeOptions;
use SecureNative\sdk\EventTypes;

Configuration

You can pass empty SecureNativeOptions object or you can set the following:

OptionTypeOptionalDefault ValueDescription
apiKeystringfalsenoneSecureNative api key
apiUrlstringtruehttps://api.securenative.com/v1/collectorDefault api base address
intervalnumbertrue1000Default interval for SDK to try to persist events
maxEventsnumbertrue1000Max in-memory events queue
timeoutnumbertrue1500API call timeout in ms
autoSendBooleantruetrueShould api auto send the events
 
 // will initialize singleton instance
 SecureNative.init({ apiKey: "Your API_KEY", maxEvents: 10, logLevel: "error" });
 // get singleton instance
 const secureNative = SecureNative.getInstance();
SecureNative secureNative = SecureNative.init(SecureNative.configBuilder()
                                        .withApiKey("API_KEY")
                                        .withMaxEvents(10)
                                        .withLogLevel("error")
                                        .build()); 
from securenative.securenative import SecureNative


securenative = SecureNative.init_with_options(SecureNative.config_builder()
                                        .with_api_key("API_KEY")
                                        .with_max_events(10)
                                        .with_log_level("ERROR")
                                        .build())
var apiKey = "API_KEY";
var sn = new SecureNative.SDK.SecureNative(apiKey, new SecureNative.SDK.Models.SecureNativeOptions(){
            ApiUrl = "https://other.domain.com",
           Interval = 1000,
           MaxEvents = 1000,
           Timeout = 1500,
           AutoSend = true
        });
require 'securenative'

begin
  SecureNative.init('YOUR_API_KEY', SecureNativeOptions.new( # Override the default options ))
rescue SecureNativeSDKException => e
  # Do some error handling
end
$options =  new SecureNativeOptions();

$options->setMaxEvents(10);
$options->setLogLevel("error");

SecureNative::init("YOUR_API_KEY", $options);

Tracking events

Once the SDK has been initialized, tracking requests are sent through the SDK instance. Make sure you build event with the EventBuilder:

Building Event Entity

const event = {
  event: EventTypes.LOG_IN,
  userId: '1234',
  userTraits: {
    name: 'Your Name',
    email: 'name@gmail.com'
  },
  context: contextFromRequest(req)
};
SecureNative secureNative = SecureNative.getInstance();

SecureNativeContext context = SecureNative.contextBuilder()
       .withIp("127.0.0.1")
       .withClientToken("SECURED_CLIENT_TOKEN")
       .withHeaders(Maps.defaultBuilder()
                   .put("user-agent", "Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405")
                   .build())
       .build();

EventOptions eventOptions = EventOptionsBuilder.builder(EventTypes.LOG_IN)
       .userId("USER_ID")
       .userTraits("USER_NAME", "USER_EMAIL")
       .context(context)
       .properties(Maps.builder()
               .put("prop1", "CUSTOM_PARAM_VALUE")
               .put("prop2", true)
               .put("prop3", 3)
               .build())
       .timestamp(new Date())
       .build();

secureNative.track(eventOptions);
from securenative.securenative import SecureNative
from securenative.event_options_builder import EventOptionsBuilder
from securenative.enums.event_types import EventTypes
from securenative.models.user_traits import UserTraits


securenative = SecureNative.get_instance()

context = SecureNative.context_builder().\
        with_ip("127.0.0.1").\
        with_client_token("SECURED_CLIENT_TOKEN").\
        with_headers({"user-agent", "Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405"}).\
        build()

event_options = EventOptionsBuilder(EventTypes.LOG_IN).\
with_user_id("USER_ID").\
        with_user_traits(UserTraits("USER_NAME", "USER_EMAIL")).\
        with_context(context).\
        with_properties({"prop1": "CUSTOM_PARAM_VALUE", "prop2": True, "prop3": 3}).\
        build()

securenative.track(event_options)
            var snEvent = new SecureNative.SDK.Models.EventOptions(EventTypes.LOG_IN)
             {
               IP = "162.247.74.201",
               RemoteIP = "10.99.98.97",
               UserAgent = "Mozilla/5.0 (Linux; U; Android 4.4.2; zh-cn; GT-I9500 Build/KOT49H) AppleWebKit/537.36 (KHTML,                      like Gecko)Version/4.0 MQQBrowser/5.0 QQ-URL-Manager Mobile Safari/537.36",
               User = new SecureNative.SDK.Models.User()
               {
                   Id = "csharp@securenative.com",
                   Email = "csharp@securenative.com",
                   Name = "CSharp"
               },
               Device = new Device("device"),
               FP = "fp",
               CID = "client_id_uuid",
               VID = "uuid",
           };

require 'securenative/event_type'

event = Event.new(event_type = type,
            ip: "162.247.74.201",
            remote_ip: "10.99.98.97",
            user_agent: 'Mozilla/5.0 (Linux; U; Android 4.4.2; zh-cn; GT-I9500 Build/KOT49H) AppleWebKit/537.36 (KHTML, like Gecko)Version/4.0 MQQBrowser/5.0 QQ-URL-Manager Mobile Safari/537.36',
            user: User.new(user_id: id, user_email: 'jon@snow.com', user_name: 'Jon Snow'),
            params: [CustomParam.new('key', 'val')]
      )
$event = array(
    'event' => EventTypes::LOG_IN,
    'context' => SecureNative::contextFromContext(),
    'userId' => '1234',
    'userTraits' => (object)[
        'name' => 'Your Name',
        'email' => 'name@gmail.com'
    ]
)

Tracking events

secureNative.track({
  event: EventTypes.LOG_IN,
  userId: '1234',
  userTraits: {
    name: 'Your Name',
    email: 'name@gmail.com'
  },
  context: contextFromRequest(req)
});
SecureNative secureNative = SecureNative.getInstance();

SecureNativeContext context = SecureNative.contextBuilder()
       .withIp("127.0.0.1")
       .withClientToken("SECURED_CLIENT_TOKEN")
       .withHeaders(Maps.defaultBuilder()
                   .put("user-agent", "Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405")
                   .build())
       .build();

EventOptions eventOptions = EventOptionsBuilder.builder(EventTypes.LOG_IN)
       .userId("USER_ID")
       .userTraits("USER_NAME", "USER_EMAIL")
       .context(context)
       .properties(Maps.builder()
               .put("prop1", "CUSTOM_PARAM_VALUE")
               .put("prop2", true)
               .put("prop3", 3)
               .build())
       .timestamp(new Date())
       .build();
from securenative.securenative import SecureNative
from securenative.event_options_builder import EventOptionsBuilder
from securenative.enums.event_types import EventTypes
from securenative.models.user_traits import UserTraits


securenative = SecureNative.get_instance()

context = SecureNative.context_builder().\
        with_ip("127.0.0.1").\
        with_client_token("SECURED_CLIENT_TOKEN").\
        with_headers({"user-agent", "Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405"}).\
        build()

event_options = EventOptionsBuilder(EventTypes.LOG_IN).\
with_user_id("USER_ID").\
        with_user_traits(UserTraits("USER_NAME", "USER_EMAIL")).\
        with_context(context).\
        with_properties({"prop1": "CUSTOM_PARAM_VALUE", "prop2": True, "prop3": 3}).\
        build()
var apiKey = "API_KEY";
var sn = new SecureNative.SDK.SecureNative(apiKey, new SecureNative.SDK.Models.SecureNativeOptions()
{
    ApiUrl = "https://api.securenative.com/collector/api/v1",
    Interval = 1000,
    MaxEvents = 1000,
    Timeout = 1500,
    AutoSend = true
});
sn.Track(new SecureNative.SDK.Models.EventOptions(EventTypes.LOG_IN)
{
    IP = "162.247.74.201",
    User = new SecureNative.SDK.Models.User()
    {
        Id = "1",
        Email = "1@example.com",
        Name = "example"
    }
});
SecureNative::track(array(
    'event' => EventTypes::LOG_IN,
    'context' => SecureNative::contextFromContext(),
    'userId' => '1234',
    'userTraits' => (object)[
        'name' => 'Your Name',
        'email' => 'name@gmail.com'
    ],
    // Custom properties
    'properties' => (object)[
        "prop1" => "CUSTOM_PARAM_VALUE",
        "prop2" => true,
        "prop3" => 3
    ]
));
curl -X POST \
  https://api.securenative.com/collector/api/v1/track \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "eventType": "sn.user.login",
    "userId": "1234",
    "userTraits" : {
      "name" : "Your Name",
      "email" : "name@gmail.com"
    },
    "request": {
       "ip": "192.100.11.130",
       "clientToken": "cc103cc1c498f10ed6a3e7a0afb7fdf37b915cd5f8a56d2eee6177740b0c7a9edc833af05694b899ff739ac01b9656562e19655660651933ccf18fbaa305498a0e99a96b1e04b86525e0dfde5dccdb15c8fc49c3da3916ee461065c9a56a73bd0f41e12be152a0e4d6040a223c3775b8edec04ec1181f464e397c2bea361fbaccc013430b91ab0cb1265b4d4e385d507172af3a0d54b47d344a2b546974f049d0eafe01894f5529a51a42a47b75ad0f99c2fcc31394b331b50e1d2022f213382",
       "headers": {
            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36",
            "Content-Type": "application/javascript",
            "Origin": "https://securenative.com/",
            "Referer": "https://securenative.com/login"
        }
    },
    "properties": {
       "prop1": "CUSTOM_PARAM_VALUE",
       "prop2": true,
       "prop3": 3
    },
    "timestamp": "2020-06-04T09:32:13.921Z"
}'

You can build an event from HttpServletRequest or from combination between event and HttpServletRequest, or HttpContext in C#:

@RequestMapping("/track")
public String track( HttpServletRequest request, HttpServletResponse response) {
    try {
        secureNative = new SecureNative(API_KEY,new SecureNativeOptions());
        Event e = new SnEvent.EventBuilder(EventTypes.LOG_IN.getType()).
                                                withUser(new User("","","your@domain.com")).
                                                build();
        Event event = secureNative.buildEventFromHttpServletRequest(request, e);
        secureNative.track(event);


    } catch (SecureNativeSDKException e) {
        e.printStackTrace();
        return "Api key is not valid";
    }
    return "tracked";
}

var apiKey = "API_KEY";
SecureNative.SDK.Models.EventOptions event1 = new SecureNative.SDK.Models.EventOptions(EventTypes.LOG_IN) {

           User = new SecureNative.SDK.Models.User()
           {
               Id = "user-id",
               Email = "user@domain.com"
           },
           IP="104.244.73.126"
       };



var ev = SecureNative.SDK.VerifyWebhook.BuildEventFromContxt(HttpContext.Current, event1,apiKey);
// you can either send null as ievent or half completed ievent object  
require 'securenative'
require 'securenative/event_type'
require 'securenative/event_options'


def login
  # Do some cool stuff here
  # ...
  # ...
  
  SecureNative.track(Event.new(
            event_type = EventTypes::LOG_IN,
            user: User.new("1", "Jon Snow", "jon@snow.com"),
            ip: "1.2.3.4",
            remote_ip: "5.6.7.8",
            user_agent: "Mozilla/5.0 (Linux; U; Android 4.4.2; zh-cn; GT-I9500 Build/KOT49H) AppleWebKit/537.36 (KHTML, like Gecko)Version/4.0 MQQBrowser/5.0 QQ-URL-Manager Mobile Safari/537.36",
            sn_cookie: "cookie"))
end

Verify endpoint

const verifyResult = await secureNative.verify({
  event: EventTypes.LOG_IN,
  userId: '1234',
  userTraits: {
    name: 'Your Name',
    email: 'name@gmail.com'
  },
  context: contextFromRequest(req)
})

console.log(res.riskLevel);
console.log(res.score);
console.log(res.triggers);
@RequestMapping("/track")
public void track(HttpServletRequest request, HttpServletResponse response) {
    SecureNativeContext context = SecureNative.contextBuilder()
                                              .fromHttpServletRequest(request)
                                              .build();

    EventOptions eventOptions = EventOptionsBuilder.builder(EventTypes.LOG_IN)
            .userId("USER_ID")
            .userTraits("USER_NAME", "USER_EMAIL")
            .context(context)
            .properties(Maps.builder()
                    .put("prop1", "CUSTOM_PARAM_VALUE")
                    .put("prop2", true)
                    .put("prop3", 3)
                    .build())
            .timestamp(new Date())
            .build();
    
    VerifyResult verifyResult = secureNative.verify(eventOptions);
    verifyResult.getRiskLevel() // Low, Medium, High
    verifyResult.score() // Risk score: 0 -1 (0 - Very Low, 1 - Very High)
    verifyResult.getTriggers() // ["TOR", "New IP", "New City"]
}
from securenative.securenative import SecureNative
from securenative.event_options_builder import EventOptionsBuilder
from securenative.enums.event_types import EventTypes
from securenative.models.user_traits import UserTraits


def track(request):
    securenative = SecureNative.get_instance()
    context = SecureNative.context_builder().from_http_request(request).build()

    event_options = EventOptionsBuilder(EventTypes.LOG_IN).\
        with_user_id("USER_ID").\
        with_user_traits(UserTraits("USER_NAME", "USER_EMAIL")).\
        with_context(context).\
        with_properties({"prop1": "CUSTOM_PARAM_VALUE", "prop2": True, "prop3": 3}).\
        build()
    
    verify_result = securenative.verify(event_options)
    verify_result.risk_level  # Low, Medium, High
    verify_result.score  # Risk score: 0 -1 (0 - Very Low, 1 - Very High)
    verify_result.triggers  # ["TOR", "New IP", "New City"]
var apiKey = "API_KEY";
var sn = new SecureNative.SDK.SecureNative(apiKey, new SecureNative.SDK.Models.SecureNativeOptions()
{
    ApiUrl = "https://api.securenative.com/collector/api/v1",
    Interval = 1000,
    MaxEvents = 1000,
    Timeout = 1500,
    AutoSend = true
});

var verified = sn.Verify(new SecureNative.SDK.Models.EventOptions(EventTypes.LOG_IN)
{
    IP = "162.247.74.201",
    User = new SecureNative.SDK.Models.User()
    {
        Id = "1",
        Email = "1@example.com",
        Name = "example"
    }
});
require 'securenative'
require 'securenative/event_type'
require 'securenative/event_options'
 
def reset_password 
    res = SecureNative.verify(Event.new(
              event_type = EventTypes::PASSWORD_RESET,
              user: User.new("1", "Jon Snow", "jon@snow.com"),
              ip: "1.2.3.4",
              remote_ip: "5.6.7.8",
              user_agent: "Mozilla/5.0 (Linux; U; Android 4.4.2; zh-cn; GT-I9500 Build/KOT49H) AppleWebKit/537.36 (KHTML, like Gecko)Version/4.0 MQQBrowser/5.0 QQ-URL-Manager Mobile Safari/537.36",
              sn_cookie: "cookie"))
                  
    if res['riskLevel'] == 'high'
        return 'Cannot change password'
    else res['riskLevel'] == 'medium'
        return 'MFA'
     end   
end
$ver = SecureNative::verify(array(
    'event' => EventTypes::VERIFY,
    'userId' => '1234',
    'context' => SecureNative::contextFromContext()
    'userTraits' => (object)[
        'name' => 'Your Name',
        'email' => 'name@gmail.com'
    ]
));
curl -X POST \
  https://api.securenative.com/collector/api/v1/verify \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "eventType": "sn.verify",
    "userId": "demo-user",
    "request": {
       "ip": "192.100.11.130",
       "clientToken": "cc103cc1c498f10ed6a3e7a0afb7fdf37b915cd5f8a56d2eee6177740b0c7a9edc833af05694b899ff739ac01b9656562e19655660651933ccf18fbaa305498a0e99a96b1e04b86525e0dfde5dccdb15c8fc49c3da3916ee461065c9a56a73bd0f41e12be152a0e4d6040a223c3775b8edec04ec1181f464e397c2bea361fbaccc013430b91ab0cb1265b4d4e385d507172af3a0d54b47d344a2b546974f049d0eafe01894f5529a51a42a47b75ad0f99c2fcc31394b331b50e1d2022f213382",
       "headers": {
            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.138 Safari/537.36"
        }
    },
    "timestamp": "2020-06-04T09:32:13.921Z"
}'

Example Response:
{
 "riskLevel" : "low",
 "score" : "0.2",
 "triggers" : ["NewDevice"]
}

Webhooks

Use verifyWebhook middleware to ensure that webhook is comming from SecureNative

const secureNative = SecureNative.getInstance();
app.post("/securewebhook", secureNative.middleware.verifyWebhook, (req, res) => {
    const {riskLevel, riskScore, triggers } = req.body;
}
@RequestMapping("/webhook")
public void webhookEndpoint(HttpServletRequest request, HttpServletResponse response) {
    SecureNative secureNative = SecureNative.getInstance();
    
    // Checks if request is verified
    Boolean isVerified = secureNative.verifyRequestPayload(request);
}
from securenative.securenative import SecureNative


def webhook_endpoint(request):
    securenative = SecureNative.get_instance()
    
    # Checks if request is verified
    is_verified = securenative.verify_request_payload(request)

var apiKey = "1234";
var sn = new SecureNative.SDK.SecureNative(apiKey, new SecureNative.SDK.Models.SecureNativeOptions());
bool isOk = SecureNative.SDK.VerifyWebhook.IsRequestFromSecureNative(HttpContext.Current, apiKey);
//if isOK is true, continue. Otherwise, consider ruturning http code 401. 

require 'securenative'


def handle_some_code(headers, body)
  sig_header = headers["X-SecureNative"]
  if SecureNative.verify_webhook(sig_header, body)
      # Handle the webhook
      level = body['riskLevel']
  else
      # This request wasn't sent from Secure Native servers, you can dismiss/investigate it
  end
end
$verified = SecureNative::getMiddleware()->verifySignature();

if ($verified) {
    // Request is trusted (coming from SecureNative) 
}
Last updated on 6/4/2020
← SDK'sNode.js →