Embedded SDK Integration

Overview

The nLink Embedded solution operates on a secure Shadow Workspace model. Your backend authenticates with nLink using a Root API Key and provisions short-lived SSO (Single Sign-On) tokens for your users. The frontend SDK then consumes this token to render the editor securely in an iframe.

• No cross-tenant data leakage: Each of your users gets an isolated shadow workspace.
• No third-party cookies required: Authentication is handled via stateless JWTs.
• True White-labeling: Hide headers, sidebars, and apply custom themes.

Step 1: Backend Authentication (SSO)

Before rendering the iframe, your backend must generate a short-lived SSO token. Never expose your Root API Key to the frontend.

Make a POST request to your self-hosted nLink instance:

curl -X POST http://<your-nlink-instance>/v1/embedded/sso \
  -H "Content-Type: application/json" \
  -d '{
    "root_api_key": "nlink_live_xxxxxxxxx",
    "external_user_id": "tenant_12345"
  }'

Parameters:

• root_api_key: Your workspace's master API key (Generated in nLink Settings).
• external_user_id: A unique identifier for your user (e.g., their User ID or Org ID in your system). nLink uses this to provision their isolated shadow workspace.

Response:

{
  "code": "00",
  "data": {
    "sso_token": "eyJhbGciOiJIUzI1NiIsIn...",
    "workspace_id": "42",
    "expires_in": 7200
  }
}

Return the sso_token and workspace_id to your frontend application.

Step 2: Frontend SDK Initialization

Include the lightweight embed.v1.js script in your frontend application. Once included, initialize the editor by passing the token and targeting a DOM container.

<!-- 1. Define the container -->
<div id="workflow-builder" style="width: 100vw; height: 100vh;"></div>

<!-- 2. Load the SDK -->
<script src="http://<your-nlink-instance>/sdk/embed.v1.js"></script>

<!-- 3. Initialize -->
<script>
  const nlinkEditor = new nLinkEmbed({
      container: '#workflow-builder',
      token: '<sso_token_from_backend>',
      workspaceId: '<workspace_id_from_backend>',
      baseUrl: 'http://<your-nlink-instance>',
      workflowId: 'new', // Set to an existing Workflow Code to edit, or 'new' to create
      theme: 'light',    // 'light' or 'dark'
      hideHeader: true,  // Hides the top navigation bar
      hideSidebar: true  // Hides the left navigation menu
  });

  // Render the iframe
  nlinkEditor.render();
</script>

Step 3: Listening to Events

The SDK securely routes cross-origin `postMessage` events from the inner iframe to your host application. You can listen to these events to react to user actions, such as saving a workflow.

// Listen for the save event
nlinkEditor.on('WORKFLOW_SAVED', (payload) => {
    console.log("Workflow saved successfully!");
    console.log("Workflow ID:", payload.workflow_id);
    console.log("Workflow Details:", payload.workflow);
    
    // Example: Save the workflow_id to your database so you can trigger it later
    saveToMyDatabase(payload.workflow_id);
});

Cleanup (SPA frameworks):

If you are using a Single Page Application framework (React, Vue, Angular), make sure to call nlinkEditor.destroy() when the component unmounts to prevent memory leaks and duplicate event listeners.

// Vue 3 Example
onUnmounted(() => {
    nlinkEditor.destroy();
});