Bindbee Embed

​

Add Bindbee Embed in your product

Bindbee Embed uses four steps to securely authenticate your customer’s integrations and allow you to embed the entire magic link flow inside your own product.

Step 1: Generate a link_token to initialize a Bindbee Embed session for your end user.

Step 2: Embed Bindbee Embed in your frontend using your frontend (using either React SDK or JavaScript CDN).

Step 3: Retrieve a temporary_token upon successful integration.

Step 4: Exchange the temporary_token for a connector_token, which authenticates future requests to the Unified API.

​

Step 1: Generate link_token

To start, generate a link_token by making a POST request to the following endpoint: https://api.bindbee.dev/api/embedded/v1/link/create-link-token.

​

What is a link_token?

A link_token is a unique code that allows you to start the linking process for integrating with third-party services like HRIS, Payroll, or ATS systems.

​

Generating the link_token?

You will need BINDBEE_API_KEY for authentication.

You will also need to send some information about end user, integration category, and the specific integration you want to connect to.

​

How to get Integration Category and Name?

To get the category and Integration name refer to Integrations page

import requests

url = 'https://api.bindbee.dev/api/embedded/v1/link/create-link-token'
api_key = '<BINDBEE_API_KEY>'
headers = {
'accept': 'application/json',
'Content-Type': 'application/json'
'Authorization': f"Bearer {api_key}",
}
data = {
"end_user_data": {
"org_name": "Acme Corp.", # Unique entity name of your customer's organisation
"origin_id": "064e1cd7-49ad-4e6d-8005-7e4c92fe9675" # Unique ID to Identify your customer's organisation
},
"category": "HRIS", # category
"integration": "bamboohr" # Integration name
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

​

Step 2: Embed Bindbee Embed in your product

You can implement Bindbee Embed using either the React SDK or our JavaScript CDN approach.

​

Option A: Using React SDK

If you are using React for your frontend, you can easily integrate the linking flow using our React SDK

​

Installation

Run one of the following commands in your React project directory:

npm install --save @bindbee/react-link

or

yarn add @bindbee/react-link

​

How to use the SDK?

Import the useBindbeeMagiclink hook and integrate it into your React application. Here’s an example:

import React from "react";
// Run this in your React project:
// npm install --save @bindbee/react-link
import { useBindbeeMagiclink } from "@bindbee/react-link";

const App = () => {
  const handleOnSuccess = (temporary_token) => {
    // Use this token to get the connector_token
    console.log("Temporary Token:", temporary_token);
  };

  const handleOnClose = () => {
    // Optional: Perform any action when the user closes the linking flow
    console.log("Linking flow closed");
  };

  const { open } = useBindbeeMagiclink({
    linkToken: "LINK_TOKEN", // Replace LINK_TOKEN with the token retrieved from previous step,
    serverUrl: "https://api.bindbee.dev", // OPTIONAL: use 'https://api-eu.bindbee.dev' for EU Region
    onSuccess: handleOnSuccess,
    onClose: handleOnClose,
  });

  return <button onClick={open}>Open Linking Flow</button>;
};

export default App;

​

How it works?

• useBindbeeMagiclink is a hook that handles the linking flow which takes following parameters as input:
  • linkToken is the token generated in Step 1.
  • serverUrl is optional parameter used to specify region. eg. use ‘https://api-eu.bindbee.dev’ to use eu region.
  • onSuccess is a callback function that is called when the linking process is successful.
  • onClose is an optional callback function that is called when the user closes the linking flow.

​

Option B: Using JavaScript CDN

If you’re using a framework or library other than React for your frontend, you can seamlessly integrate the linking flow using our JavaScript CDN.

​

Installation

Add the following script tag to your HTML:

<script src="https://cdn.bindbee.dev/initialize.min.js"></script>

​

Usage

Here is a sample JavaScript code snippet for the implementation.

// Initialize BindbeeEmbed
window.BindbeeEmbed.initialize({
  linkToken: "LINK_TOKEN", // Replace with your link_token
  serverUrl: "https://api.bindbee.dev", // OPTIONAL: use 'https://api-eu.bindbee.dev' for EU Region
  onSuccess: (temporary_token) => {
    // Handle the temporary token
    console.log("Temporary Token:", temporary_token);
  },
  onClose: () => {
    // Optional: Handle close event
    console.log("Linking flow closed");
  },
});

// Open the linking flow (e.g., on button click)
function openLinkingFlow() {
  window.BindbeeEmbed.open();
}

// Clean up when needed
function cleanup() {
  window.BindbeeEmbed.destroy();
}

​

HTML implementation example

Here’s a complete HTML code snippet for the implementation, including the JavaScript code:

<!DOCTYPE html>
<html>
  <head>
    <title>Bindbee Integration</title>
    <script src="https://cdn.bindbee.dev/initialize.min.js"></script>
  </head>
  <body>
    <button onclick="openLinkingFlow()">Connect Integration</button>

    <script>
      window.BindbeeEmbed.initialize({
        linkToken: "LINK_TOKEN",
        serverUrl: "https://api.bindbee.dev", // OPTIONAL: use 'https://api-eu.bindbee.dev' for EU Region
        onSuccess: (temporary_token) => {
          console.log("Success! Temporary Token:", temporary_token);
        },
        onClose: () => {
          console.log("Integration window closed");
        },
      });

      function openLinkingFlow() {
        window.BindbeeEmbed.open();
      }
    </script>
  </body>
</html>

​

Step 3: Get temporary_token

After a successful linking process, you will receive a temporary_token. This token is used to retrieve the connector_token.

​

Step 4: Get connector_token using the temporary_token

To get the connector_token, make a GET request to the following endpoint: https://api.bindbee.dev/api/embedded/v1/connectors/connector_token/{temporary_token}

You will need BINDBEE_API_KEY for authentication.

​

What is connector_token?

connector_token is required for authorizing your Bindbee API requests effectively. for more information about connector_token you can refer here

​

Getting the connector_token?

Here’s an example on how to get the connector_token:

import requests

url = 'https://api.bindbee.dev/api/embedded/v1/connectors/connector_token/{temporary_token}'
headers = {
'accept': 'application/json',
'Authorization': 'Bearer <BINDBEE_API_KEY>'
}

response = requests.get(url, headers=headers)
print(response.json())