Passbyme2fa-client NPM

PassByME two factor authentication client

This library provides you with functionality to handle PassByME authentications.

For further information on PassByME please visit: www.passbyme.com and sign up for a free account. You can download our API documentation after login.

Installation
Usage Handling messages Sending messages Tracking messages Canceling messages SessionInfo Errors BadArgumentError MissingArgumentError HttpError PassByMEError
Release History

Installation

npm install passbyme2fa-client --save

Usage

To use the PassByME authentication SDK first you have to acquire the following:

Account authentication PFX and its password

You can get these after registering at www.passbyme.com, by hitting the "Sign up for free" button. To complete the registration you will need an Android or iOS device with the PassByME application installed.

If you login after registration you can download the PFX from the Application menu. You can add new applications to your registration by hitting the "New application". The application (along with its Application Id) will appear in the table below.

We suggest you to read the available User Guides and API documentation before you continue with the integration. You can download these from the Documentation section of the administartion website after login.

1. Require passbyme2fa-client in your code.

var pbm = require('passbyme2fa-client')({ /* params */	});

The params object consist of the following:

pfx: the authentication pfx. (See: https.request for details)
passphrase: the authentication pfx's passphrase. (See: https.request for details)
hostname: The address of the PassByME service to use. This parameter is optional. by default the SDK will connect to our public service. The PassByME service url is the following: - auth-sp.passbyme.com
message: The default message attached to each PassByME authentication request. Optional, de default value is 'Request for PassByME authentication'
You can supply any parameter accepted by http.request or https.request to influence the connection.

Throws MissingArgumentError when a required parameter is missing.

Example

var pbm = require('passbyme2fa-client')({
	pfx: fs.readFileSync('auth.pfx'), //required
	passphrase: 'password', //required
	hostname: 'auth-sp.passbyme.com', //optional, defaults to auth-sp.passbyme.com
	message : 'Request for PassBy[ME] authentication' //optional, defaults to 'Request for PassBy[ME] authentication'
});

2. Handling Messages

2.1 Sending messages

pbm.sendMessage(function(error, messageId){ /* code */ }, { /*params*/}, { /*httpParams*/}));

The callback function is called when the operation is finished. It should accept two paramters where first is an error parameter and the second is a sessionInfo data structure describing the session if there was no error.

Throws MissingArgumentError when a required parameter is missing. The error.propertyName and error.message properties both contain the name of the missing property. Throws BadArgumentError when a required parameter is malformed. The error.propertyName and error.message properties both contain information about the malformed property and the description of the problem.

The error object can be an instance of HttpError, or a PassByMEError.

The params object consists of the following:

recipients: A javascript array containing the PassByME ID-s of the recipients
subject: The subject of the message
body: 'The body of the message
availability: The availability of the message in seconds
type: One of pbm.MESSAGETYPE.AUTHORIZATION, pbm.MESSAGETYPE.MESSAGE or pbm.MESSAGETYPE.ESIGN. Use AUTHORIZATION to send authenticaion and authorization messages with arbitrary body. Use MESSAGE to send a general message with arbitrary body, or use ESIGN if the message body is containing an esign JSON You can supply any parameter accepted by http.request or https.request as the httpParams object to influence the connection.

Example

pbm.sendMessage(function(err,messageId){
	//handle error
	//process result
}, {
	recipients: ['pbmId1', 'pbmId2', 'pbmId3'],
	subject: 'test',
	body: 'body',
	availability: 23,
	type: pbm.MESSAGETYPE.MESSAGE
});

2.2 Tracking messages

pbm.trackMessage(function(error, messageId){ /* code */ }, { /*params*/, /*httpParams*/});

Throws MissingArgumentError when a required parameter is missing. The error.propertyName and error.message properties both contain the name of the missing property.

The error object can be an instance of HttpError, or a PassByMEError.

The params object consists of the following:

messageId: The Id of the message to check You can supply any parameter accepted by http.request or https.request as the httpParams object to influence the connection.

Example

pbm.trackMessage(function(err,result){
	//handle error
	//process result
}, {
	messageId: myMessageId
});

2.3 Canceling messages

pbm.cancelMessage(function(error){ /* code */ }, { /*params*/});

The callback function is called when the operation is finished. It should accept a paramter, an error parameter. If the error is null, then the operation succeeded.

Throws MissingArgumentError when a required parameter is missing. The error.propertyName and error.message properties both contain the name of the missing property.

The error object can be an instance of HttpError, or a PassByMEError.

The params object consists of the following:

messageId: The Id of the session to cancel
You can supply any parameter accepted by http.request or https.request to influence the connection.

Example

pbm.cancelMessage(function(err){
	//handle error
}, {
	messageId: myMessageId
});

2.4 sessionInfo

The sessionInfoObject describes the state of a message session. It consits of the following fields:

messageId: The ID of the message that can be used to reference the message
expirationDate: The date and time until the message can be downloaded with the PassByME applications
recipients: An array of recipient objects. Each object consist of the following fields - userId: The PassByME ID of the user represented by this recipient object - status: The delivery status of this message for this user

Available statuses are:

PENDING: Initial status of the message.
NOTIFIED: The recipient has been notified about a new message.
DOWNLOADED: The recipient has downloaded the message, but has not uploaded the evidence yet.
SEEN: The recipient has seen the message and uploaded the evidence.
NOT_SEEN: The recipient has not seen the message.
NOT_NOTIFIED: The recipient has not received the notification.
NOT_DOWNLOADED: The recipient received the notification about the message but has not downloaded the message
NO_DEVICE: The message could not be sent because the recipient had no PassByME ready device that supports messaging.
FAILED: The message could not be sent because of an error.
DISABLED: The message could not be sent because the recipient is disabled.
CANCELLED: The message was cancelled by the sender.
APPROVED: Authentication has finished successfully.
DENIED: The user has cancelled the authentication.

Example

{
   "messageId" : " YzX95zUA1et2ijQ",
   "expirationDate" : "2015-06-11T13:06:12.658+02:00",
   "recipients" : [
       { "userId" : "pbmId1", "status" : "PENDING" },
       { "userId" : "pbmId2", "status" : "PENDING" },
       { "userId" : "pbmId3", "status" : "PENDING" }
   ]
}