Skip to main content

​
Installation

npm install @handled/link-sdk

​
Usage

import authenticate from '@handled/link-sdk';

// Get link token from your backend
const linkToken = 'your-link-token';

authenticate(linkToken)
  .then((response) => {
    console.log('Connected:', response);
    // {result: 'success', integration: 'shiphero', integrated_account_id: 'acc_123'}
  })
  .catch((error) => {
    console.log('Error:', error);
  });

​
How It Works

1

Generate Token

Generate a link token from your backend
2

Call authenticate()

Call authenticate() with the token
3

Popup Opens

A popup opens with the connection UI
4

User Authenticates

User selects integration and authenticates
5

Handle Response

Promise resolves on success, rejects on error
From your backend: 
curl -X POST 'https://api.usehandled.io/api/v1/ipaas/link-token' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "customer-123"
  }'

​
Response Handling

​
Success

{
  result: 'success',
  integration: 'shiphero',
  integrated_account_id: 'acc_123'
}

​
Errors

The promise rejects when:
  • User closes the popup
  • Authentication fails
  • Validation fails (if configured)
authenticate(linkToken).catch((error) => {
  if (error.type === 'validation_error') {
    // Credentials invalid
  } else if (error.type === 'user_closed') {
    // User closed popup
  } else {
    // Other error
  }
});
Generate a shareable link instead of embedding: 
https://ipaas.usehandled.io/connect-account?link_token={link_token}
Send this to customers who need to connect accounts outside your app.

​
React Example

import { useState } from 'react';
import authenticate from '@handled/link-sdk';

function ConnectButton({ linkToken }) {
  const [loading, setLoading] = useState(false);

  const handleConnect = async () => {
    setLoading(true);
    try {
      const result = await authenticate(linkToken);
      console.log('Connected:', result);
    } catch (error) {
      console.error('Connection failed:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleConnect} disabled={loading}>
      {loading ? 'Connecting...' : 'Connect Account'}
    </button>
  );
}