Setup Railz Connect

Railz Connect™ is what your end-users will interact with to link their service providers to your product. It will be embedded directly into your client-facing application for a seamless user experience.

Railz Connect™ will automatically handle all of the back and forth with the service providers, as well as deal with all the different types of authorization flows used by the service providers to protect your end users from unauthorized access.

Let's quickly setup Railz Connect™ to suit your brand and preferences.

Setup Railz Connect™

There are two ways to integrate Railz Connect™ into your application:

  1. via NPM
  2. via CDN Script

You can follow our Quickstart Guide to quickly get Railz Connect up and running quickly or follow steps in our GitHub examples.


Node Package Manager can be used to install Railz Connect into your frameworks. Follow the steps below to install.

Run the following command to install the package.

// with yarn
yarn add @railzai/[email protected]

// with npm
npm install @railzai/[email protected] --save

Setup the script in your framework of choice

<div id='railz-connect' #railzConnect></div>
import { AfterViewInit, Component, ElementRef, ViewChild } from '@angular/core';

import RailzConnect from '@railzai/railz-connect';

    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
export class AppComponent implements AfterViewInit {
    @ViewChild('railzConnect', { static: false }) railzConnect: ElementRef;

    ngAfterViewInit(): void {
        const widget = new RailzConnect();
            parentElement: this.railzConnect.nativeElement,
            widgetId: '<Your Widget Id>',
            // Add additional Railz Connect configuration  paramaters here
import RailzConnect from '@railzai/railz-connect';
import {useEffect, useRef} from "react";

function App() {
  const ref = useRef();

  useEffect(() => {
    const widget = new RailzConnect();
      parentElement: ref.current,
      widgetId: '<Your Widget Id>',
      // Add additional Railz Connect configuration  paramaters here
  return (
    <div id='railz-connect' ref={ref}></div>

export default App;

<script setup>
  import { ref, onMounted } from 'vue'
  import RailzConnect from "@railzai/railz-connect";

  const railzConnect = ref()

  onMounted(() => {
    const widget = new RailzConnect();
      parentElement: railzConnect.value,
      widgetId: '<Your Widget Id>',
      // Add additional Railz Connect configuration  paramaters here

  <div ref="railzConnect"></div>


NPM Examples

More examples are provided in CodeSandbox.

Via CDN Script

On the dashboard go to Connect > Setup in the left sidebar navigation menu of the Dashboard.


Railz Connect Setup. Click to Expand.

This method allows you to embed railz connect in the <body> tag of your HTML. To integrate Railz Connect™ into your website or application, copy the following script and paste it into your website's HTML source code before closing the </body> tag.


The code must be inserted into any page you want to display Railz Connect on. Note that this will not slow down your web pages.

Railz always publishes non-breaking updates and improvements to Railz Connect™. To ensure that you're using the latest version of Railz Connect™, do not download and host the railz-connect.js file within your app.

<!-- Insert this div where you want Railz Connect to be initialized -->
<div id="railz-connect"></div>

<!-- Start of Railz Connect script -->
<script src=""></script>
  var widget = new RailzConnect();
    parentElement: document.getElementById('railz-connect'),
    widgetId: 'wid-bf51a64f-1d10-4dab-9e63-7bbbd123edd6'
    // Add additional Railz Connect configuration  paramaters here
<!-- End of Railz Connect script -->


Configure your Railz Connect

You have a variety of design configuration options to fit your brand experience. See Parameters for more details.

IP Whitelisting (Optional)

For additional security, you can restrict the server IP addresses that can embed Railz Connect™. To enable IP Whitelisting, from the IP Whitelist page, you must add the public IP addresses of all application servers embedding Railz Connect™.


IP Whitelisting

  • IP Whitelisting does not apply to Railz Connect in Sandbox Mode.
  • For testing Railz Connect on your local environment with a non-sandbox widgetId, you will need to whitelist your local server IP address. You can setup a local server using a tunnel service like ngrok and whitelisting the ngrok IP. You would need to ping your ngrok URL to get the IP address being used. You might need to whitelist multiple IP addresses depending on your location.
  • IPv6 is currently not supported.

To manage your IP Whitelist:

  1. In the left sidebar navigation menu, go to Connect > IP Whitelist.
  2. Click the Add IP button to add an IP to the whitelist.
Railz Connect IP Whitelist. Click to Expand.Railz Connect IP Whitelist. Click to Expand.

Railz Connect IP Whitelist. Click to Expand.

  1. Enter the IP address you would like to whitelist, enter a Label to easily identify your IP, then click Save changes.

Add IP Address. Click to Expand.

Service Not Available Screen

Railz Connect™ will display service not available screen if:

  • You have not configured and enabled any integrations.
  • You have reached your connection limit on a free plan.
  • Accessed Railz Connect from an IP not in your IP whitelist (if enabled).

Railz Connect Not Available. Click to Expand.

Preventing Duplicate Accounting Connections

When a user links their accounting service provider account through Railz, a new connection is created. Two connections created for the same set of credentials (account) at the same accounting service provider will be considered a duplicate and will result in the most recent one being invalidated.

Preventing a user from accidentally linking a connection they have already linked can help avoid confusing behaviour in your application and will also prevent you from potentially being billed for both connections.


See Connection Disconnected for more details on subscribing to connection disconnected webhook event.

Did this page help you?