> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a connection

> OnRamp is Leen's embeddable onboarding component that allows your users to easily create new connections or update existing connections. As an embeddable component, OnRamp is designed to be integrated directly into your application workflow.

## 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. Handle Response from OnRamp
4. Regions and custom overrides (optional)
5. Create Connections

<Info>
  **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.
</Info>

<Steps>
  <Step title="Create Connection Invite Token">
    <Tip>
      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](/onramp/update-connection) guide.
    </Tip>

    You can provision a new token by making a POST request to the [Create Connection Invite Token API](/api-reference/onramp/create-connection-invite-token) with the following payload:

    ```json theme={null}
    {
        "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.

      ```json theme={null}
      {
          "vendor": "SNYK",
          "options": {
              "oauth2_redirect_urls": {
                  "success": "https://echo.free.beeceptor.com/?status=success",
                  "error": "https://echo.free.beeceptor.com/?status=error"
              }
          }
      }
      ```
  </Step>

  <Step title="Initialize Leen's OnRamp component">
    Leen's OnRamp component has been [published to npm library](https://www.npmjs.com/package/@leendev/onramp) and can be installed using npm, yarn, bun, or any other package manager.

    ```bash theme={null}
    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:

    ```typescript theme={null}
    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;
    ```
  </Step>

  <Step title="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.

    ```typescript theme={null}
    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:

    ```json theme={null}
    {   
        "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": ""
    }
    ```

    <Tip>
      ### 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:

      ```typescript theme={null}
          useEffect(() => {
              window.addEventListener('leenConnectionError', (event) => {
                  // handle error tracking here
                  console.log('leenConnectionError', event);
              });
          }, []);
      ```
    </Tip>
  </Step>

  <Step title="Regions and custom overrides (optional)">
    ### Regions

    By default, OnRamp will use Leen's US region. If you are using a different Leen region, you can set OnRamp to use a different region by passing in the `region` in the `config` prop.

    For example, if you are using Leen's EU Central 1 region, you can pass in the `eu-c1` region to the `config` prop like so:

    ```typescript theme={null}
        <LeenOnRamp
            token={connectionInviteToken}
            setLeenOnRampResponse={setLeenOnRampResponse}
            setShowLeenOnRamp={setIsModalOpen}
            config={{ region: "eu-c1" }}
        />
    ```

    ### Custom overrides

    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)
    4. Font Family (defaults to Inter). To override the font family, you will have to provide both:
       * `fontFamily`: the name of the font family
       * `fontUrl`: the url to the font stylesheet (what you would normally add to the head of your html document)
    5. Font Size. You can override the font size for specific text elements in the OnRamp component.
       * `headerSize`: the size of the heading font (defaults to 1.25rem)
       * `bodySize`: the size of the body font (defaults to 1rem)
       * `buttonSize`: the size of the button font (defaults to 0.875rem)
           <Info>
             The font size can be in any standard css unit, like `px`, `rem`, `em`, etc.
           </Info>
    6. Dark Mode. By default, OnRamp will use a light theme. You can override this by setting `darkMode` to `true` to switch to a dark theme.
    7. Dark Mode Colors. If the dark mode theme does not match your application's colors, you can override the primary and secondary colors used in the component by passing in `darkModeColors` with the following keys:

       * `primary`: hex code for the primary color
       * `secondary`: hex code for the secondary color

           <Info>
             Dark mode colors are only used when `darkMode` is set to `true`.
           </Info>

    ```typescript theme={null}
        // ...

        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}
            fontFamily="font-family-name"
            fontUrl="https://fonts.googleapis.com/css2?family=font-family-name&display=swap"
            fontSizes={{
                headerSize: "24px",
                bodySize: "18px",
                buttonSize: "12px",
            }}
            darkMode={true}
            darkModeColors={{
                primary: "#2A004E",
                secondary: "#500073",
            }}
        />
    ```
  </Step>

  <Step title="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.

    <img src="https://mintcdn.com/leen/vQ2Rhs44KY1LGMJC/images/onramp/create-modal.png?fit=max&auto=format&n=vQ2Rhs44KY1LGMJC&q=85&s=4d106f3302adbc4aa235877c59e6ca7c" alt="" width="1068" height="1312" data-path="images/onramp/create-modal.png" />
  </Step>
</Steps>

## Reference

For reference, we have created a [public GitHub Repository](https://github.com/leeninc/onRamp-demo-host-app) 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.