Skip to main content
Embedding UBIK tools into your own application provides a powerful way to extend your product’s capabilities. This guide will walk you through the process of securely embedding a tool using an <iframe>.
1

Configure Allowed Origins

To prevent unauthorized domains from embedding your tools, you must first configure a list of Allowed Origins for your API key. This is a critical security step. An “origin” is the combination of a protocol, domain, and port (e.g., https://yourapp.com).You can set the allowed origins for your API keys in the user settings page on the UBIK dashboard.

Go to API Key Settings

For local development, you can add origins like http://localhost:3000. For production, ensure you only add the domains where your application is hosted.
2

Fetch Embedding Information

Before you can render the <iframe>, your application’s frontend needs to fetch the embedding details from the UBIK API. This is done by making a GET request to the /tools/{tool_id}/embed-info endpoint.This endpoint provides two crucial pieces of information:
  1. Tool Details: The schema, name, description, etc.
  2. Access Token: A short-lived JSON Web Token (JWT) that the embedded <iframe> will use to authenticate itself.
curl -X GET "https://app.ubik-agent.com/api/v1/tools/YOUR_TOOL_ID/embed-info" \
     -H "X-API-KEY: YOUR_API_KEY"
Security Best Practice: Your secret UBIK API key should never be exposed in your frontend application. The call to /embed-info should be made from your backend server, which can then pass the resulting short-lived access_token and tool details to the client.
3

Render the iframe

Once your frontend has the embedding information, you can construct the <iframe> URL and render it. The access_token from the embed-info endpoint must be passed as a jwt query parameter to the iframe’s source URL.Here is a simplified example using React:
React Example
import React, { useState, useEffect } from 'react';

const EmbeddedTool = ({ toolId }) => {
  const [embedInfo, setEmbedInfo] = useState(null);

  useEffect(() => {
    // In a real app, this would fetch from your backend
    const fetchEmbedInfo = async () => {
      try {
        const response = await fetch(`/api/get-tool-embed-info?toolId=${toolId}`);
        const data = await response.json();
        setEmbedInfo(data);
      } catch (error) {
        console.error("Failed to fetch embed info:", error);
      }
    };

    fetchEmbedInfo();
  }, [toolId]);

  if (!embedInfo) {
    return <div>Loading Tool...</div>;
  }

  // Append the access token as a query parameter.
  const iframeSrc = `https://app.ubik-agent.com/embed/tools/${embedInfo.id}?jwt=${embedInfo.access_token}`;

  return (
    <iframe
      src={iframeSrc}
      title={embedInfo.name}
      width="100%"
      height="600px"
      frameBorder="0"
    />
  );
};

export default EmbeddedTool;
Using a direct API Key: For scenarios where you prefer not to use the /embed-info endpoint (e.g., server-side rendering), you can also authenticate by passing your UBIK API key directly as the apiKey query parameter.const iframeSrc = https://app.ubik-agent.com/embed/tools/YOUR_TOOL_ID?apiKey=YOUR_API_KEY`;`However, for client-side applications, using the short-lived access_token is strongly recommended to avoid exposing your secret API key.
4

Customize the Embedded Tool

You can customize the appearance and behavior of the embedded tool by adding query parameters to the <iframe> source URL.Here is a list of available parameters:
  • jwt (string): A short-lived JSON Web Token obtained from the /tools/{tool_id}/embed-info endpoint. This is the recommended method for client-side authentication.
  • apiKey (string): Your UBIK API key. This can be used for authentication instead of a JWT, but it is less secure for client-side applications as it may expose your secret key.
  • theme (‘light’ | ‘dark’): Sets the default color theme for the tool’s UI. If not provided, it defaults to the user’s system preference.
  • showThemeToggle (boolean): If set to true, a theme toggle switch will be displayed in the tool’s header, allowing users to switch between light and dark mode.
  • showLangToggle (boolean): If set to true, a language selector will be displayed, allowing users to change the display language.
Example URL with customization:
https://app.ubik-agent.com/embed/tools/YOUR_TOOL_ID?jwt=YOUR_JWT&theme=dark&showThemeToggle=true
By following these steps, you can securely embed UBIK’s powerful tools directly into your application, creating a seamless and integrated experience for your users.