Embedded SDK

Magic Link hands your customer a URL and needs no frontend code. The Embedded SDK does the same job inside your product: your user clicks a button in your UI, authorizes their HR system in an overlay, and never leaves your app.

A four-step diagram. Step 1, initiate the SDK: your server POSTs to Bindbee for a link_token, and your app's integrations page shows a Connect button on BambooHR. Step 2, authentication flow: the user approves access to each data model and enters their BambooHR subdomain. Step 3, get temporary token: a Connection Established confirmation returns a temporary_token. Step 4, get connector token: your server sends the temporary_token in a GET and receives the connector_token. — The full round trip: your server creates a link token, the user authorizes in the overlay, and the temporary token that comes back is exchanged — server-side again — for the connector token you store.

Steps 1 and 3 run on your server. Both use your API key, which must never reach the browser.

Step 1: Create a link token

A link token authorizes one linking session for one end user. Full reference: Create Link Token.

POST /api/embedded/v1/link/create-link-token
Authorization: Bearer <BINDBEE_API_KEY>

{
  "end_user_data": {
    "org_name": "Acme Inc",
    "origin_id": "acme-4471",
    "email": "hr@acme.com"
  },
  "category": "HRIS",
  "integration": "bamboohr"
}

{
  "link_token": "KJDXZk8zC8Tdr-suQCy7zkALZVLjhKXyMd83leqheEGQpBx_evXrHA"
}

Field	Required	Notes
`end_user_data.org_name`	Yes	The customer organization this connector belongs to. Minimum 2 characters.
`end_user_data.origin_id`	Yes	Your own unique identifier for the end user. This is how you match the connector back to a record in your system.
`end_user_data.email`	No	Contact email for the end user.
`category`	Yes	One of `HRIS`, `ATS`, `LMS`, `CUSTOM`.
`integration`	Yes	The integration slug, for example `bamboohr`. See Integrations.

Call this from your server, never the browser. It takes your Bindbee API key, and exposing that key would let anyone read every connector in your account.The key also decides the environment: a Development key creates a Development connector, a Production key a Production one. See Environments.

Step 2: Open the link flow

Pass the token to the SDK. Opening the flow mounts a full-screen overlay on top of your app, where the user signs in to their HR system and authorizes access.

React
JavaScript

npm install --save @bindbee/react-link

React 18 or later. The package ships its own TypeScript types.

App.jsx

import { useBindbeeMagiclink } from "@bindbee/react-link";

const App = ({ linkToken }) => {
  const { open } = useBindbeeMagiclink({
    linkToken,
    onSuccess: (temporaryToken) => {
      // Send this to your backend to exchange for a connector token
      fetch("/api/bindbee/exchange", {
        method: "POST",
        body: JSON.stringify({ temporaryToken }),
      });
    },
    onClose: () => console.log("Linking flow closed"),
  });

  return <button onClick={open}>Connect your HR system</button>;
};

The hook returns { open }. Call it from a click handler.

For any frontend that is not React. Add the script, then initialize it.

<script
  src="https://cdn.bindbee.dev/initialize.min.js"
  integrity="sha512-1L1XqHiVgenLFd95eE8fqJ7o6kje+5+3IN7K0cuwNP6feTrYAeNTdpeqR1e2HgThSb5Bj+USqJeNiyEE9KBtfA=="
  crossorigin="anonymous"
></script>

window.BindbeeEmbed.initialize({
  linkToken: "LINK_TOKEN",
  onSuccess: (temporaryToken) => {
    // Send this to your backend to exchange for a connector token
  },
  onClose: () => console.log("Linking flow closed"),
});

// Then, from a click handler
window.BindbeeEmbed.open();

initialize() throws if linkToken is missing, and open() throws if called before initialize(). Call window.BindbeeEmbed.destroy() to remove the overlay and its message listener.integrity verifies the script has not been tampered with, and crossorigin="anonymous" is required for that check to run. An unminified build is at https://cdn.bindbee.dev/initialize.js, with integrity sha512-2Rzjv7TfBrXNCgB1wLTnpZupTZh6/JS0tQkKTGRu9fC7IAK4ahbPzcu29VUGHOmRPquLNU6RkLyt6yVuKR60DQ==.

Both take the same options:

Option	Type	Notes
`linkToken`	`string`	Required. The token from Step 1. One token, one linking session.
`serverUrl`	`string`	Set to `https://api-eu.bindbee.dev` for the EU region. Defaults to US.
`onSuccess`	`(temporary_token) => void`	Fires when the user completes the flow. You get a temporary token, not the connector token.
`onClose`	`() => void`	Fires when the overlay is dismissed, whether or not linking succeeded.

Register one instance per page. A second one logs an error and will not behave predictably. In React, lift the hook to a shared parent if several places need to trigger it.

Step 3: Exchange for a connector token

The temporary token from onSuccess is not an API credential. Send it to your backend and exchange it for the real one. Full reference: Get Connector Token.

GET /api/embedded/v1/connectors/connector_token/{temporary_token}
Authorization: Bearer <BINDBEE_API_KEY>

Response

{
  "connector_token": "jk23h4jk23hk4j2h3kj4h23kjh4k23jh4k2j3h4",
  "connector_id": "123e4567-e89b-12d3-a456-426614174000"
}

Store the connector_token against the customer record you identified with origin_id. It is the credential every later call uses, as the X-Connector-Token header on unified endpoints, Passthrough, and custom fields. This exchange uses your API key, so it belongs on your server too. Treat the returned connector_token as a secret: it grants access to that customer’s HR data.

Behavior worth knowing


Overlay	A fixed, full-screen iframe with id `magic-link-flow`, prepended to `document.body`.
Page scroll	Locked while the overlay is open, restored on close.
Dismissal	Closing from inside the flow removes the iframe and fires `onClose`.
Repeat opens	Calling `open()` while the overlay is already mounted does nothing.
Styling	The flow is Bindbee-hosted. Branding is configured in the dashboard, not through the SDK.

Errors

Status	Meaning	Fix
`401`	API key missing or invalid.	Check the `Authorization` header on your server call.
`403`	Credentials valid but not permitted for this resource.	Confirm the category and integration are enabled for your account.
`404`	No connector found for that temporary token.	Tokens are single use and short-lived. Re-run the flow.
`422`	Validation failed.	Check `org_name`, `origin_id`, `category` and `integration`.
`429`	Rate limit exceeded.	Retry after `Retry-After`. See Rate limits.

npm package

@bindbee/react-link on npm.

Authentication

API keys and connector tokens.

Webhooks

Get notified when a new connector finishes its first sync.

Docs MCP

Point your AI assistant at these docs while you build.

Reading & Writing Data

Extending the Model

SDK & MCP

Data Models

Workspace & Access

Going Live

Troubleshooting

Step 1: Create a link token

Step 2: Open the link flow

Step 3: Exchange for a connector token

Behavior worth knowing

Errors

npm package

Authentication

Webhooks

Docs MCP

​Step 1: Create a link token

​Step 2: Open the link flow

​Step 3: Exchange for a connector token

​Behavior worth knowing

​Errors

​Related

npm package

Authentication

Webhooks

Docs MCP

Step 1: Create a link token

Step 2: Open the link flow

Step 3: Exchange for a connector token

Behavior worth knowing

Errors

Related