JavaScript SDK

Learn how to use the Keyfax Web API JavaScript SDK.

The Keyfax Web API JavaScript SDK is a self-contained JavaScript file with no external dependencies. To use the Keyfax Web API JavaScript SDK you'll need to include the Keyfax JavaScript SDK within your web pages. The following script tag should be placed towards the bottom of pages that wish to utilitize the Keyfax Web API JavaScript SDK....

<script src="https://keyfax.com/Interview/assets/js/sdks/webapi/basic/v1/sdk.min.js"></script>   

We would recommend copying and linking to this file locally within your integration and avoid linking to this file externally.

To ensure your Keyfax API signing key is never revealed to end users client side requests into the Keyfax Web API must use a JSON Web Token or JWT for verification - this is also true for our JavaScript SDK. You cannot use your API key or Signing key when using the JavaScript Web API SDK and instead need to use a JSON Web Token to verify requests.

The JWT required for client side verification should be first obtained via a secure server side call to GET /api/v1/token. This server side call will require your Keyfax Web API key and Signing key. Once the JSON Web Token has been obtained via server side code it can then be shared with the client to verify subsequent client side requests into the Keyfax Web API.

Obtaining the JSON Web Token via secure server side code is easy using the Keyfax Web API .NET SDK as shown in the following C# code example...

using Keyfax.WebApi.Sdk.Basic.v1

...

var client = new KeyfaxClient(c =>
{
    c.BaseUrl = "https://keyfax-url/interview/";
    c.HostName = "Dev";        
    c.ApiKey = "YourApiKey";
    c.SigningKey = "YourSigningKey";
});

var response = await client.GetJsonWebTokenAsync();
if (response.Success && response.Data != null)
{
    txtHiddenJWTField.Value = response.Data.Token;
}

The generated JSON Web Token will only be valid for 24 hours after creation. For long running client side sessions you should use the JSON Web Token generated by the server side call to GET /api/v1/token to call POST /api/v1/token on the client side to periodically generate a new JSON Web Token. See "Renewing the JSON Web Token" within this guide.

Once you've obtained a valid JSON Web Token via server side code you can then share this with the client and configure the Keyfax Web API JavaScript SDK as shown below...

$(document).ready(function () {

    // Get JWT generated on the server
    var $txtHiddenJWTField = $('#<% = txtHiddenJWTField.ClientID %>');

    // Add Keyfax Web API JavaScript SDK to local variable 
    var sdk = window.KeyfaxWebApiSdk;

    // Configure the JavaScript SDK, providing the Keyfax URL, host name & JSON Web Token
    sdk.init({
        url: "https://keyfaxserver.com/Interview",
        hostName: "Dev",
        token: $txtHiddenJWTField.val()
    });

});

You'll notice in the example above our server side code added the JSON Web Token to a hidden form field called txtHiddenJWTField. We then retrieve the token stored within this hidden form field via client side code to configure the Keyfax Web API JavaScript SDK. There are many ways to share content generated on the server with the client but in this example to keep things simple we used a hidden form field to store the JSON Web Token.

Once the Keyfax Web API JavaScript SDK has been configured with the URL, host name & JSON Web Token as shown above you can then use the methods provided by the Keyfax Web API JavaScript SDK to make verified requests into the Keyfax Web API.

Launching Keyfax

IMPORTANT The start -up data you provide to Keyfax should be customized to suit your environment & integration. The start -up data presented in these examples is minimal and for demonstration purposes only. Please contact Omfax Systems for assistance with configuring your start -up data to fully leverage the intelligent scripting features offered by Keyfax.

The following JavaScript shows how you can obtain Keyfax launch data via client side JavaScript code upon a button click...

// Post start-up data to get launch details on button click
$("#btnJsPostStartUpData").click(function (e) {

    e.preventDefault();

    // Get JWT generated on the server
    var $txtHiddenJWTField = $('#<% = txtHiddenJWTField.ClientID %>');

    // Add Sdk to local variable 
    var sdk = window.KeyfaxWebApiSdk;

    // Configure the client
    sdk.init({
        url: "https://keyfaxurl.com/Interview",
        hostName: "Dev",
        token: $txtHiddenJWTField.val()
    });

    // Build some sample minimal start-up date. This will need to be customized depending 
    // on your host and Keyfax configurations and is only provided for demonstration purposes
    var startUpData = {     
        mode: { value: "RD" },
        userName: { value: "administrator" },
        password: { value: "" },
        company: { value: "RDFL_Dev" },            
        scriptSet: { value: "RD" }               
    };

    // Post start-up data to get Keyfax launch data
    sdk.startup.post(startUpData, function (response) {
        if (response) {
            console.log("Url: " + response.launchUrl);
            console.log("Guid: " + response.guid);
            console.log("Company: " + response.company);
        }
    });

});

Obtaining Keyfax Results

The JavaScript below shows how to check for results for a previously launched Keyfax session using the Keyfax Web API JavaScript SDK when a button is clicked...

// Check for results using the supplied launch details
$("#btnJsPostResultsData").click(function (e) {

    e.preventDefault();

    // Get JWT generated on the server
    var $txtHiddenJWTField = $('#<% = txtHiddenJWTField.ClientID %>');

    // Add Sdk to local variable 
    var sdk = window.KeyfaxWebApiSdk;

    // Configure the client
    sdk.init({
        url: "https://keyfaxurl.com/Interview",
        hostName: "Dev",
        token: $txtHiddenJWTField.val()
    });

    // Build launch data, the results from calling sdk.startup.post
    // can also be supplied when calling sdk.results.post. 
    // These values are hard coded here for demonstration  purposes only
    var data = {
        guid: "ac712681-ce8b-443f-b317-34f5b28f22fa",
        company: "RDFL_Dev"
    };

    // Get results for the given Keyfax session via POST /api/v1/results
    sdk.results.post(data, function (response) {
        if (response) {
            console.log(JSON.stringify(response))
        }
    });

});

Renewing the JSON Web Token

Renewing the JSON Web Token is made easy using the Keyfax Web API JavaScript SDK and is just a few lines of code as shown below. By default the JSON Web Token expires after 24 hours. If you expect clients to remain within your browser application for more than 24 hours you may wish to periodically call this code to issue clients with a new token.

// Call POST /api/v1/token to obtain a new JSON Web Token
sdk.token.post(function (response) {
    if (response) {                 
        console.log("My new JSON Web Token is " + response.token);
    }
});

For this request to succeed the current JSON Web Token supplied within the Authorization header to POST /api/v1/token must still be valid. If the current JSON Web Token has expired this request will fail returning a 401 Unauthorized response.

Error Handling with the Keyfax Web API JavaScript SDK

Developers can use the onError method as shown below to handle any exceptions that may be thrown by the Keyfax Web API JavaScript SDK...

sdk.onError(function (config, xhr, ajaxOptions, thrownError) {
    console.log("Client returned an error! - " + JSON.stringify(xhr));
});

Available SDK Methods

A brief summary of each method available within the Keyfax Web API JavaScript SDK is provided below.

• startup.get (GET /api/v1/startup) Returns minimal example start-up data for the current master configuration.

• startup.post (POST /api/v1/startup) Post start-up data to Keyfax to obtain launch results.

• results.post (POST /api/v1/results) Post launch results to Keyfax to obtain diagnostic results.

• token.post (POST /api/v1/token) Renews a JSON Web Token given a currently valid JSON Web Token.

• key.get (GET /api/v1/key) Obtain initial API & Signing Keys for authentication.