Continuous Two Factor Authentication

This section explains how to integrate your web service with Spriv’s Continuous Two Factor Authentication API.

First complete the Getting Started steps and start the API phase by adding a username, once the username is added you should pair manage_users/pair/<user id> that username with the user’s phone. The pairing process identify for Spriv which username is using a particular phone so that Spriv will be able to send authentication push notification to that phone.

Once the pairing completes successfully you can start authenticating the users with the following Two Factor Authentication methods:

Adaptive Two Factor Authentication (AKA Continuous Two Factor Authentication)
Allow/Deny Push Notification
Two Way SMS Authentication
TOTP Authentication:

Add Users

Use the /manage_users API to add a single user to your company. Upon successful completion you will get the ID of the new user. Later you can use this ID to send pairing Email to that user.

Request:

Request
Type: POST
Url: https://app.spriv.com/manage_users
Data:
{
        "spriv_secret": "your spriv secret ",
        "spriv_key": "your spriv key",
        "user": {
                  "email": "<user email address>",
                  "first_name": "first name",
                  "last_name": "last name",
                  "mobile_phone": "user phone number",
                  "person_id": "user person id"                
        }
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Parameters

#	Name	Type	Validations
1	spriv_secret	String	Required
2	spriv_key	String	Required
3	email	String	A valid Email is reqiured
4	first_name	String	Required
5	last_name	String	Required
6	mobile_phone	String	A valid phone number which starts with country code
7	person_id	String	Not Mandatory

Return value samples:

{
"user_id": 10,
"status": 200,
"message": "User created successfully."
}

Update User

Use the /manage_users/<user id> API to update a single user. Upon successful completion you will get the ID of the new user. Later you can use this ID to send pairing email to that user.

Request:

Request
Type: PUT
Url: https://app.spriv.com/manage_users/<user id>
Data:
{
        "spriv_secret": "<your spriv secret>",
        "spriv_key": "<your spriv secret>",        
        "user": {
                  "email": "example@company.com",
                  "first_name": "joe",
                  "last_name": "doe",
                  "mobile_phone": "914444556677",
                  "person_id": "12277"                
        }
  
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Parameters:

#	Name	Type	Validations
1	spriv_secret	String	Required
2	spriv_key	String	Required
3	email	String	A valid Email is reqiured
4	first_name	String	Required
5	last_name	String	Required
6	mobile_phone	String	A valid phone number which starts with country code
7	person_id	String	Not Mandatory

Return value samples:

{
"status": 200,
"message": "User details updated successfully!",
  "user": {
    "id": 10,
    "first_name": "joe",
    "last_name": "doe",
    "email": "example@company.com",
    "person_id": "12277",
    "mobile_phone": "914444556677",
    "status_id": "bypass",
    "status_timeout": null
  }
}

Delete user

Use API /manage_users/<user id> to delete a user from the system.

Request:

Request
Type: DELETE
Url: https://app.spriv.com/manage_users/<user id>
Data:
{
  "spriv_secret": "your spriv secret",
  "spriv_key": "your spriv key" 
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Parameters:

#	Name	Type	Validations
1	spriv_secret	String	Required
2	spriv_key	String	Required

Return value samples:

{
"status": 200,
"message": "User removed successfully."
}

Pairing

Send a paring email to your user /manage_users/pair/<user id>. If a user is already paired to the system, calling to this API will unpair the user in addition to sending a new pairing email.

A crucial data pointer is the user’s Email address, which will be used by the pairing API in order to send the pairing link via Email. The pairing link will correlate the user’s cell phone with the user’s username. The Email pairing works by sending a unique 32 bit URL to the user. After receiving the unique URL via Email, the user can complete the pairing in just two simple clicks: Click on the URL link and then click on the pair button.

Spriv will send push notification back to your server once the user successfully completes the pairing step and at that point you can start authenticating the user. More information about pairing.

Video: How the pairing process works?

Request:

Request
Type: POST
Url: https://app.spriv.com/manage_users/pair/<user id>
Data:
{
  "spriv_key": "your spriv key",
  "spriv_secret": "your spriv secret",
  "email": "example@company.com",
  "id": 83
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Parameters:

#	Name	Type	Validations
1	spriv_secret	String	Required
2	spriv_key	String	Required
3	email	String	A valid Email is reqiured
4	first_name	String	Required
5	last_name	String	Required
6	mobile_phone	String	A valid phone number which starts with country code
7	person_id	String	Not Mandatory
8	recovery_code	String	Auto Generated
9	qr_code	String	Auto Generated
10	ip_addresses	String	Safe IPs. Comma seperated

Return value samples:

Request
Type: POST
Url: https://app.spriv.com/manage_users/pair/<user id>
Data:
{
  "spriv_key": "your spriv key",
  "spriv_secret": "your spriv secret",
  "email": "example@company.com",
  "id": 83
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Continuous Two Factor Authentication

Continuous Two Factor Authentication also known as Adaptive Authentication: /authentication/adaptive_authentication is the fastest second factor authentication 2nd channel in the world. Upon login your user will get an authentication request sent to his phone, and have the option to Allow or Deny. If the user chooses to Allow Spriv may automate all future transaction if the same particular device fingerprint is identified near the phone.

Request:

Request
Type: POST
Url: https://app.spriv.com/authentication/adaptive_authentication
Data:
{
        "spriv_secret": "your spriv secret",
        "spriv_key": "your spriv key",
        "username": "username of user",
        "os": "Operating system name",
        "browser": "browser name",
        "computer_fingerprint": "user computer fingerprint",
        "ip_address": "user IP address",
        "bypass_code": "your bypass code here"
        "poll": true
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Parameters:

#	Name	Type	Validations
1	spriv_secret	String	Required
2	spriv_key	String	Required
3	email	String	A valid Email is reqiured
4	os	String	User OS platform name
5	browser	String	User browser name
6	computer_fingerprint	String	User computer fingerprint
7	ip_address	String	User IP address

Return value samples:

{
    "status": 200,
    "message": "User verification request sent."
}

//After this user will get request on callback url with decision and transaction id. We can send more details if needed.

{
  "status": 206,
  "message": "Sent Successfully; Pending Decision; Check URL for answer.",
  "poll_service_url": <System generated polling url>
}

Polling result of Adaptive Authentication

Request
Type: POST
Url: https://app.spriv.com/poll/<unique polling ID>
Data:
{
    "spriv_secret": "your spriv secret",
    "spriv_key": "your spriv key",
    "username": "your user name ",
    "poll": true
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Response:

{
    "status": 200,
    "message": 1
}

//If no transactionfound with such UID then
{
  "status": 404,
  "message": "No matching transaction found."
}

//No response from mobile devise
{ 
  status: 206, 
  message: 'No response from mobile device yet. Please try again' 
}

Allow / Deny Push Notification

Allow / Deny push authentication API: /authentication/allow_deny_authentication Present a custom message with an option to Allow or Deny. Spriv’s platform allows you to send an authentication message to the user with two options: Allow or Deny. There is no option to automate Allow/Deny Authentication.

Request:

Request
Type: POST
Url: https://app.spriv.com/authentication/allow_deny_authentication
Data:
{
  "spriv_secret": "your spriv secret",
  "spriv_key": "your spriv key",
  "totp": "742479",
  "username": "your username",
  "ip_address": "1.1.1.1"
  "poll": true
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Parameters:

Return value samples:

{
    "status": 200
}

//Implement listner with GET request on URL  "/report_decision/" It will send decision and transaction id in params

{
  "decision"=>"1", 
  "transaction_id"=>"4C3EEA25CC20454CA7CEE929BCE50D94"
}

//if callback url not set then

{
    status: 416, 
    errors: ["Callback URL not set. Please set it first."]
}

//when poll: true is set
{
"status": 206,
"message": "User verification request sent to device. Pending Decision. Check URL for answer.",
"poll_service_url": "polling url from system"
}

//when poll: true not sent.
{
"status": 206,
"message": "User verification request sent to device."
}

Polling results of Allow/Deny Authentication

Request
Type: POST
Url: https://app.spriv.com/poll/<unique polling ID>
Data:
{
    "spriv_secret": "your spriv secret",
    "spriv_key": "your spriv key",
    "username": "your user name ",
    "poll": true
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Response:

{
    "status": 200,
    "message": 1
}

//If no transactionfound with such UID then
{
  "status": 404,
  "message": "No matching transaction found."
}

//No response from mobile devise
{ 
  status: 206, 
  message: 'No response from mobile device yet. Please try again' 
}

Two Way SMS Authentication

Two Way SMS API: /authentication/sms_authentication Present a custom SMS message that required a “YES” reply from the user’s mobile phone in order to successfully complete authentication. There is no option to automate Two Way SMS authentication requests.

Request:

Request
Type: POST
Url: https://app.spriv.com/authentication/sms_authentication
Data:
{
        "spriv_secret": "your spriv secret",
        "spriv_key": "your spriv key",
        "username": "username of user",
        "ip_address": "1.1.1.1",
        "bypass_code":"your bypass code here"
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Parameters:

#	Name	Type	Validations
1	spriv_secret	String	Required
2	spriv_key	String	Required
3	username	String	A valid username is reqiured
4	ip	String	IP address of the user
5	bypass_code	String	Bypass code is expected when user allowed to bypass by admin

Return value samples:

//IF unable to send SMS then response will be:
{
          status: 408,
          errors: ['Unable to send SMS. Please try again later.']
 }

//If SMS sent : 

 {
    status: 206,
    message: 'Verification SMS sent successfully.'
 }

//polling url if poll set to true
{
            poll_service_url:  "https://app.spriv.com/poll/<polling id>"
            status: 206,
            message: 'Sent Successfully; Pending Decision; Check URL for answer.'
 }

TOTP Authentication

TOTP authentication API: /authentication/totp the good old TOTP that we all are familiar with. Works just by having a battery in your mobile device. The TOTP authentication is using the username and the 6-digit code from Spriv’s mobile app. TOTP can be combined with any Spriv’s authentication in order to provide a three-factor authentication that is as fast and has the same user intervention as other platforms provide for two-factor authentication.

Request:

Request
Type: POST
Url: https://app.spriv.com/authentication/totp
Data:
{
        "spriv_secret": "your spriv secret",
        "spriv_key": "your spriv key",
        "totp": <TOTP CODE>,
        "username": <username of user>  
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Parameters:

#	Name	Type	Validations
1	spriv_secret	String	Required
2	spriv_key	String	Required
3	email	String	A valid Email is reqiured
4	totp	String	6 digit code which user can get from Spriv Mobile app

Return value samples:

//ON Success
{
"status": 200,
"user": {
"id": 4,
"first_name": "joe",
"last_name": "doe",
"email": "example@company.com",
"person_id": "",
"mobile_phone": "914444556677",
"status_id": "bypass",
"status_timeout": 22
}
}

//ON Failure

{
"status": 405,
"errors": [
  "Incorrect OTP. Please try again"
],
}
//2.

{
"status": 406,
"errors": [
  "No such user found with this username"
],
}

Verify end user phone number

Using API /manage_users/verify_phone_pin Spriv will send a seven digits code via SMS to the phone number provided by the end user in order to verify that the end user provided the correct phone number. The end user will need to enter via web the seven digits code and Spriv will check that the end user provided the correct code.

Request
Type: POST
Url: https://app.spriv.com/manage_users/verify_phone_pin
Data:
{
  "spriv_secret": "your spriv key",
  "spriv_key": "your spriv secret",
  "user": {
        "phone_pin": "phone pin number from sms",
        "email": "user email address"        
  }
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Parameters:

#	Name	Type	Validations
1	spriv_secret	String	Required
2	spriv_key	String	Required
3	email	String	A valid Email is reqiured
4	phone_pin	String	Phone Pin is sent to user mobile number.

Response:

//If no matching user found
{
          status: 415,
          errors: ['Unable to find matching user. Please try again.'] 
}


//FAILURE RESPONSE
{
"status": 414,
"errors": [
  "Wrong PIN number. Please enter correct one or resend SMS."
],
"user": {
"id": 11,
"first_name": "joe",
"last_name": "doe",
"email": "example@company.com",
"person_id": "1222",
"mobile_phone": "914444556677",
"status_id": "bypass",
"status_timeout": null
}
}


//SUCCESS RESPONSE
{
  "status": 200,
   "message": "Phone number verified successfully",
  "user": {
    "id": 11,
    "first_name": "joe",
    "last_name": "doe",
    "email": "example@company.com",
    "person_id": "1222",
    "mobile_phone": "914444556677",
    "status_id": "bypass",

    "status_timeout": null
  }
}

Request
Type: POST
Url: https://app.spriv.com/manage_users/resend_phone_pin
Data:
{
  "spriv_secret": "your spriv secret",
  "spriv_key": "your spriv key",
  "user": {
        "email": "example@company.com"        
  }
}
Required Headers:  Content-Type = application/json
Accept = application/json
apiversion = 1

Response:

{
  "status": 200,
  "message": "Phone pin sent successfully. Please check."
}

//Failure response
 {
   status: 413,
   errors: ['Unable to find matching user. Please try again.']
 }

Add Users

Request:

Parameters

Return value samples:

Update User

Request:

Parameters:

Return value samples:

Delete user

Request:

Parameters:

Pairing

Video: How the pairing process works?

Request:

Parameters:

Return value samples:

Continuous Two Factor Authentication

Request:

Parameters:

Return value samples:

Polling result of Adaptive Authentication

Response:

Allow / Deny Push Notification

Request:

Parameters:

Return value samples:

Polling results of Allow/Deny Authentication

Response:

Two Way SMS Authentication

Request:

Parameters:

Return value samples:

TOTP Authentication

Request:

Parameters:

Return value samples:

Verify end user phone number

Parameters:

Response:

Resend Phone PIN (Verify end user phone number)

Response:

Home

Two Factor Authentication

Company

Sign Up

Documentation

Client Login

Interesting links

LATEST NEWS

Categories

BUSINESS HOURS