Getting Started with Leen OnRamp

This guide will walk you through the steps to integrate OnRamp, Leen’s embeddable onboarding component, into your application. Here’s a quick overview of the steps involved:

  1. Create a connection invite token
  2. Initialize Leen’s OnRamp component
  3. Custom overrides (optional)
  4. Create Connections

Note: Currently, Leen’s OnRamp component only supports embedding into React applications. We can add support for other frameworks, please contact us to learn more.

1

Create Connection Invite Token

This step is for creating a new connection using OnRamp. If you want to update a connection, refer to the Update a connection with OnRamp guide.

You can provision a new token by making a POST request to the Create Connection Invite Token API with the following payload:

{
    "vendor": "CROWDSTRIKE"
}

A connection invite token will be returned for a specific vendor - this token can be used to only create one new connection for the vendor specified in the payload.

  • you can optionally pass in any connection options, like you would when creating a new connection via our API. These options will not be visible to the user, but will directly be applied to the connection when it is created.

    {
        "vendor": "SNYK",
        "options": {
            "oauth2_redirect_urls": {
                "success": "https://echo.free.beeceptor.com/?status=success",
                "error": "https://echo.free.beeceptor.com/?status=error"
            }
        }
    }
    
2

Initialize Leen's OnRamp component

Leen’s OnRamp component has been published to npm library and can be installed using npm, yarn, bun, or any other package manager.

npm install @leendev/onramp

Once installed, you can import the component into your React application and initialize it with the connection invite token. Here is an example of how you can use the OnRamp component in your React application:

import React, { useState } from "react";
import { LeenOnRamp, LeenOnRampResponse } from "@leendev/onramp";

interface LeenOnRampDemoProps {
connectionInviteToken: string;
}

const LeenOnRampDemo: React.FC<LeenOnRampDemoProps> = ({ connectionInviteToken }) => {
    // connection creation/ update response
    const [onRampResponse, setLeenOnRampResponse] = useState<LeenOnRampResponse | undefined>(undefined);

    // control opening and closing of modal
    const [isModalOpen, setIsModalOpen] = useState(false);

    return (
        <div>
            <button onClick={() => setIsModalOpen(true)}>
            Open Leen OnRamp
            </button>
            {isModalOpen && (
                <LeenOnRamp
                    token={connectionInviteToken}
                    setLeenOnRampResponse={setLeenOnRampResponse}
                    setShowLeenOnRamp={setIsModalOpen}
                />
            )}
        </div>
    );
}

export default LeenOnRampDemo;
3

Handle Response from OnRamp

Use the useEffect hook with onRampResponse to handle the response from the OnRamp component and perform any necessary actions in your application. Whenever onRampResponse changes, the effect will run, allowing you to process the response data.

useEffect(() => {
    if (onRampResponse) {
        // perform your desired actions here 
        console.log(onRampResponse);
    }
}, [onRampResponse]);

onRampResponse will be an object of type LeenOnRampResponse, which can be imported in your application as seen in the snippet above. For reference, here is what the response object would look like:

{   
    "data": {
        "id": "59851f06-9867-4b9c-81d2-c9a3b1d44177",
        "vendor": "SENTINELONE",
        "is_active": true,
        "refresh_interval_secs": 14400,
        "timeout_secs": 3600,
        "organization_id": "12345678-1234-1234-1234-1234567890",
        "oauth2_authorize_url": null,
        "identifier": null
    },
    "httpStatus": 200,
    "message": ""
}

Catching and handling error events

OnRamp will also emit an error event when connection creation fails. You can catch this event and handle it accordingly in your application.

To do this, you can add an event listener for the leenConnectionError event in your application like so:

    useEffect(() => {
        window.addEventListener('leenConnectionError', (event) => {
            // handle error tracking here
            console.log('leenConnectionError', event);
        });
    }, []);
4

Custom overrides (optional)

You can optionally override some settings for the OnRamp component. Specifically, you can change:

  1. Primary color (defualts to Leen’s brand colors)
  2. Logo (defaults to Leen’s logo)
  3. Docs URLs for specficic vendors (defaults to Leen’s docs)
    // ...

    vendorToDocsMappings = {
        "SNYK": "https://link.to/docs/snyk",
        "CROWDSTRIKE": "https://link.to/docs/crowdstrike",
        "SENTINELONE": "https://link.to/docs/sentinelone",
    }
    
    // ...

    <LeenOnRamp
        token={connectionInviteToken}
        setLeenOnRampResponse={setLeenOnRampResponse}
        setShowLeenOnRamp={setIsModalOpen}
        // optional overrides
        primaryColor="#000000"
        logoUrl="https://link.to/logo"
        docsUrlOverrides={vendorToDocsMappings}
    />
5

Create Connections

That’s it! Your users should now be able to create new connections or update existing connection within your application. OnRamp will open up as a modal in your application and your users will be presented with an interface to provide the right credentials for the vendor - via secrets or OAuth.

Reference

For reference, we have created a public GitHub Repository showcasing how to integrate Leen OnRamp into a React application. This GitHub repo contains a simple React application that demonstrates how to use Leen OnRamp to create connections with vendors supported by Leen.