LaunchKey Platform SDK for Node.js and JavaScript I/O

Use this SDK to interact with the LaunchKey Platform API in your Node.js or JavaScript I/O application.

Before you can begin using the Platform API, you need a service. If you have not created a service yet, you can use our Getting Started Guide to create one.

Installation

Download Source

Node.js SDK on GitHub

Clone Source

$ git clone https://github.com/LaunchKey/launchkey-node.git

Node.js Package Manager (NPM)

Node.js SDK on NPM

$ npm require --save launchkey-sdk

Instantiate an SDK Client

Definition

LaunchKey(serviceKey, secretKey, privateKey[, publicKeyTTL[, apiBaseUrl]]);

Parameters

serviceKey:number Unique 10-digit Service key from your Service details tab in dashboard.
secretKey:string Secret Key from your Service's keys tab in dashboard.
privateKey:string Private key of the RSA key pair for your service.
publicKeyTTL:number ( 300 ) Time to live in seconds for public key obtained from the Platform API during a ping call. Defaults to 300 seconds (5 minutes).
apiBaseUrl:string ( |api_v1_url| ) Base URL for the Platform API endpoint. Defaults to the production version 1 endpoint.

Example

var LaunchKey = require("launchkey-sdk"),
  serviceKey = "1234567890",
  secretKey = "secret_key",
  privateKey = "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----";

var launchKey = new LaunchKey(serviceKey, secretKey, privateKey);

Authentication vs. Authorization

Authentication is used when a user is being requested to create a session within a service. A session can be remotely revoked by a user executing a clear or clear all action from a linked device or the dashboard.

Authorization is used to get approval for a singular point in time like a transaction or a secondary authentication factor. It does not create an active session and users cannot log out.

Authenticating A User

Authentication creates a LaunchKey Service session. To authenticate a user, use the authenticate() method with the user's username, user push ID, or Directory User identifier as well as success and error callback functions.

Definition

LaunchKey.authenticate(username, success, error)

Parameters

username:string Platform Username, user push ID, or end-user identifier for the user
success:function Callback function called when the request is successful. The callback is passed single parameter which is a string whose value identifies the authentication request.
error:function Callback function called when the request encounters an error. The callback is passed a single parameter which is a JavaScript Error object.

Example

launchKey.authenticate(
    "LaunchKeyUserName",
    function (authRequestId) {
        console.log("Authentication request successful with identifier: " + authRequestId);
    },
    function (error) {
        console.error("Error processing authentication request!", error);
    }
);

Authorize A Transaction

Authorize a transaction using the authorize() method with the user's LaunchKey username, user push ID, or Directory User identifier as well as success and error callback functions.

Definition

LaunchKey.authorize(username, success, error)

Parameters

username:string LaunchKey username, user push ID, or end-user identifier for the user
success:function Callback function called when the request is successful. The callback is passed single parameter which is a string whose value identifies the authentication request.
error:function Callback function called when the request encounters an error. The callback is passed a single parameter which is a JavaScript Error object.

Example

launchKey.authorize(
    "LaunchKeyUserName",
    function (authRequestId) {
        console.log("Authorization request successful with identifier: " + authRequestId);
    },
    function (error) {
        console.error("Error processing authorization request!", error);
    }
);

Determine Status Of An Incomplete Auth Request

Once you've sent an auth request to a user with either the javascript authenticate or javascript authorize method, You can check the status of that auth request with getStatus.

Note

Auth requests remain valid for 5 minutes.

Server Side Events vs. Polling

Although polling with getStatus can be used to complete the launch process, it is highly advised to use the javascript server side events methodology of implementing a callback endpoint and using the handleCallback method.

Examples for each methodology can be found in the example apps section on the page.

Definition

LaunchKey.checkStatus(authRequestId, accepted, denied, pending, error)

Parameters

authRequestId:string Identifier of the Authentication/Authorization request whose status is being checked. The value would have been passed to the success callback from either authenticate or authorize.
accepted:function Callback function called when the user has accepted the Auth request. The callback is passed single parameter which is an AuthRequest object.
denied:function Callback function called when the user has denied the Auth request. The callback is passed single parameter which is an AuthRequest object.
pending:function Callback function called when the user not yet responded to the Auth request. The callback is passed single parameter which is the same authRequestId passed to checkStatus().
error:function Callback function called when the request encounters an error. The callback is passed a single parameter which is an JavaScript Error object.

Example

var error = function (error) {
        console.log("Error encountered: [" + error.code + "] " + error.message);
    },
    poll = function (authRequestId) {
        launchKey.checkStatus(
            authRequest,
            function (authRequest) {
                console.log("User accepted auth request " + authRequest.getId());
            },
            function (authRequest) {
                console.log("User denied auth request " + authRequest.getId());
            },
            poll,
            error
        );
    };
launchKey.authenticate("LaunchKey Username", poll, error);

Check Status Of Accepted Auth Request

Once a user has accepted an Auth request, you will need to verify the user is still authorized and has not logged out. The isAuthorized() function is used for this purpose.

Definition

LaunchKey.isAuthorized(authRequestId, authorized, unauthorized, error)

Parameters

authRequestId:string Identifier of the Authentication/Authorization request whose authorization status is being checked. The value would have been passed to the success callback from either authenticate or authorize.
authorized:function Callback function called when the Auth request is still authorized. The callback is passed single parameter which is an AuthRequest object with every applicable attribute populated.
unauthorized:function Callback function called when the Auth request is no longer authorized. The callback is passed single parameter which is an AuthRequest object with every applicable attribute populated.
error:function Callback function called when the request encounters an error. The callback is passed a single parameter which is a JavaScript Error object.

Example

launchKey.isAuthorized(
    authRequestId,
    function () {
        console.log("Request is still authorized");
    },
    function () {
        console.log("Request is no longer authorized");
    },
    function (error) {
        console.error("Error encountered: [" + error.code + "] " + error.message);
    }
);

When A User Logs Out

If a user logs out from within your website or app, you should inform our API so we can take your Service out of the user's authorization list.

Definition

LaunchKey.clear(authRequestId)

Parameters

authRequestId:string Identifier of the Authentication/Authorization request for which the user is logging out.
success:function Callback function called when the remote logout has been successfully processed. The callback has no parameters.
error:function Callback function called when the request encounters an error. The callback is passed a single parameter which is a JavaScript Error object.

Example

launchKey.clear(
    authRequestId,
    function () {
        console.log("Logged out " + authRequest.getId());
    },
    function (error) {
        console.error("Error encountered: [" + error.code + "] " + error.message);
    }
);

Creating A Directory User

If you are implementing an authenticator service, you will likely need a programmatic way to create users.

Definition

LaunchKey.createWhiteLabelUser(identifier, success, error)

Parameters

identifier:string Permanent and unique identifier of this user within your service. This identifier will be used to authenticate the user as well as link additional devices to the user's account within your white label group.
success:function Callback function called when the end-user has been successfully created. The callback has a single parameter of a WhiteLabelUser object .
error:function Callback function called when the request encounters an error. The callback is passed a single parameter which is a JavaScript Error object.

Example

launchKey.createWhiteLabelUser(
    identifier,
    function (whiteLabelUser) {
        cli.ok("User with identifier of \"" + identifier + "\" created with:");
        cli.ok("    QR Code URL: " + whiteLabelUser.getQrCodeUrl());
        cli.ok("    Code: " + whiteLabelUser.getCode());
    },
    function (error) {
        console.error("Error encountered: [" + error.code + "] " + error.message);
    }
);

Server Side Events (Callbacks)

Server side events, or callbacks, occur out of band as asynchronous events and are triggered by user interaction with the a LaunchKey Authenticator Mobile App or Dashboard. The user interactions that are currently handled are Clear/Log Out and Launch Response. The SDK Client will determine the type of server side event that triggered the callback and process it appropriately.

Definition

launchKey.handleServerSideEvent(queryStringParameters, authorized, unauthorized, clear, error)

Parameters

queryStringParameters:object A collection of properties whose values are strings representing the values of an associated query string parameter. For example, a query string like ?clear=clearValue&signature=SignatureValue would be represented as an object like this: { clear: "clearValue", signature: "SignatureValue" }
authorized:function Callback that will be passed an AuthRequest object as its only parameter when the server side event was an auth response and the user has accepted the auth request. Example: authorized({AuthRequest} authRequest).
unauthorized:function Callback that will be passed an AuthRequest object as its only parameter when the server side event was an auth response and the user has rejected the auth request. Example: unauthorized({AuthRequest} authRequest).
clear:function Callback that will be called when the server side event is a remote logout request. The callback function will be passed a user hash as its only parameter. The user hash is provided to enable matching with the user hash received from the auth request for identifying the user requesting to log out. Example: clear({string} userHash).
error:function Error callback that will be passed an Error. Example: error({Error} error).

Example

launchKey.handleServerSideEvent(
    qs.parse(url.parse(request.url, true).query),
    function (authRequest) {
        user.authenticated(authRequest);
    },
    function (authRequest) {
        user.denied(authRequest);
    },
    function (userHash) {
        user.logout(userHash);
    },
    function (error) {
        console.error("Error encountered: [" + error.code + "] " + error.message);
    }
);

For a better example, see the server.js file in the Connect Example App.

WhiteLabelUser Object

Object with data identifying a end-user including device linking data.

Definition

LaunchKey.WhiteLabelUser(identifier, qrCodeURL, code)

Parameters

identifier:string Permanent and unique identifier of this user within your service. This identifier will be used to authenticate the user as well as link additional devices to the user's account within your white label group.
qrCodeURL:string URL to a QR code image that will facilitate easily linking a users device.
code:string Code that will facilitate linking a users device by manually entering the code.

Methods

getIdentifier():string Returns the identifier value originally passed to the createWhiteLabelUser method.
getQrCodeUrl():string Returns the QR Code URL will be a URL string that will provide a QR code that can be used by services in a directory to link a device with a directory user.
getCode():string Returns a code that can be entered into services in a directory to link a device with a directory user.

AuthRequest Object

An AuthRequest object is a value object used to provide access to data associated with an authentication/authorization response.

The object's constructor receives all values for the new AuthRequest object.

Definition

LaunchKey.AuthRequest(id[, userHash[, userPushId[, organizationUserId[, deviceId]]]])

Parameters

id:string The unique identifier for the authentication/authorization request
userHash:string A hash of the username for a Service user.
userPushId:string The unique value to initiate an authorization request from the service for a directory user.
organizationUserId:string This value will only be returned if the service is under an organization. It is the unique string that identifies the user across the entire organization.
deviceId:string The unique identifier for the device with which the user responded to the request.

Methods

getId():number The unique identifier for the authentication/authorization request.
getUserHash():string A hash of the username for a Service user.
getUserPushId():string The unique value to initiate an authorization request from the service for a directory user.
getOrganizationUserId():string This value will only be returned if the service is under an organization. It is the unique string that identifies the user across the entire organization.
getDeviceId():string The unique identifier for the device with which the user responded to the request.

Example

var AuthRequest = require("launchkey-sdk").AuthRequest,
authRequest = new AuthRequest("auth request ID", "user hash", "user push ID");

User Contributed

LaunchKey links to user contributed code as a resource to its community. LaunchKey does not in any way guarantee or warrant the quality and security of these code bases. User contributed code is supported by the creators. If you do find a link from the site to user contributed code that is malicious or inappropriate in any way, please report that link to LaunchKey immediately and we will investigate the claim. Submit any issue to LaunchKey support at https://launchkey.com./support. ×