Singular Key Developer Guide

Getting Started

Common Authenication APIs

Sample Flows

Application Integrations

Widget integration

Integrate An Application With Singular Key Using The Singular Key Widget

Overview

Use the Singular Key Widget to run the flow within a modal on your application page. This reduces any UI customization needed to make the flow match your branding. This integration method is well-suited to flows that involve UI nodes.

  • Links to Redirect and API docs
  • Admin docs reference, both Owen's and Mike's

Prerequisites

  • A PingOne trial or subscription license.
  • A Singular Key application that's associated with a flow.
  • (Optional) If you want to reuse the server-side Javascript in the examples here, we're using Fastify as our Node.js framework.
  • (Optional) If you want to reuse the HTML example here, we're using Handlebars for HTML templating.

Workflow

  1. If you've not already created a Singular Key application, and associated it with a flow, see ...[Owen's admin docs]

  2. In the Singular Key console, click Applications, and open the application for the flow you want to integrate with your app.

  3. You'll need the following values from the General tab of your Singular Key application:

    • Company ID
    • API Key

Example

This is a simple hello-world application. The elements of interest are how to specify the Singular Key API URL, your company ID, and API key to get a Singular Key token, which then integrates your single-page app with the Singular Key application and associated flow.

<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8">

<head>
    <title>Simple HTML/JS Showing the Widget Method</title>
</head>

<body>
    <h3>
        The Widget method for Singular Key app integration
    </h3>
    <br>
    <p>Widget will be displayed below:</p><br>
    <div id="widget" class="skWidget">Widget appears here</div>

    <script type="text/javascript" src="https://devapi.singularkey.com/latest/singularkey.js"></script>
    <script>
        //*** Populate the following parameters from your Singular Key environment ***/
        const skApiBaseUrl = "https://devapi.singularkey.com/v1";
        const companyId = "<your-company-ID>";
        const skApiKey = "MO53xVRs0OhLQxptTStSaZUwojoFWxgpOtnmvnkNj1ZIiy3GdfGzwBwFjJyDzBm03fUHl13TGY6Ze50P0jxJoXA76AnFKAt2MHwMutF2sEzN77ozXnExxqxRlfwODCekudB0JUGoS2vxTeuXQPXWYTLd8V6EQPXg2D3ak8cjoLQ6SxoyAN6z2eIFquQt9S2CYVqRuHXCwje8SONVHD211po2Ubqs3zf5tkrdowHtfOSgw9XHiSbaBtxxxxxxxxxx";
        const skFlowId = "<your-flow-ID>";

        //*** Build the get SK Token URL. ***/
        const skGetTokenUrl = skApiBaseUrl + "/company/" + companyId + "/sdkToken";

        //*** Add the API Key from your Singular Key Application ***/
        var headers = new Headers();
        headers.append("X-SK-API-KEY", skApiKey);

        var requestOptions = {
            method: 'GET',
            headers: headers,
            redirect: 'follow'
        };

        //*** Retrieve the Singular Key token ***/
        fetch(skGetTokenUrl, requestOptions)
            .then(response => response.json())
            .then(responseData => {
                var props = {
                    config: {
                        method: "runFlow",
                        apiRoot: skApiBaseUrl,
                        accessToken: responseData.access_token,
                        companyId: companyId,
                        flowId: skFlowId
                    },
                    useModal: false,
                    successCallback,
                    errorCallback,
                    onCloseModal
                };
                /*** Invoke the Singular Key Widget ***/
                console.log(props)
                singularkey.skRenderScreen(document.getElementsByClassName("skWidget")[0], props);
            })
            .catch(error => console.log('error', error));

        function successCallback(response) {
            console.log(response);
        }

        function errorCallback(error) {
            console.log(error);
        }

        function onCloseModal() {
            console.log("onCloseModal");
        }
    </script>

</body>

</html>

Redirect integration

API integration