Embed AI Assistants & Dashboards

Put a governed Colrows AI Assistant or Dashboard directly inside your own application. This guide covers how an external application obtains an integration token and embeds either surface using a plain iframe or the provided JavaScript loader - plus the security model, token lifecycle, and troubleshooting.

Integration overview

1. An organization administrator creates a client API key in Colrows.
2. The client backend calls POST /api/integration/login with a Colrows user, password, and apiKey.
3. Colrows returns a session token in payload.token.
4. The client supplies that token to restricted AI Assistant or Dashboard embeds.
5. Public dashboards can be embedded without a token.

The token supplied by the client is used directly. Colrows removes it from the visible iframe URL but does not exchange or automatically refresh it - the client is responsible for obtaining a replacement token when it expires. One active token may be used across multiple assistant and dashboard embeds.

Part 1 - Create and manage an integration API key

An organization administrator creates and manages keys from Administration → Settings → API Keys. Treat every API key as a secret.

1. Sign in to Colrows as an organization administrator.
2. Open Administration → Settings.
3. Select the outer API Keys tab beside Permissions.
4. Review existing keys, including their name, creation date, expiry date, and status.
5. Select Add API key.
6. Enter a descriptive key name and choose an expiry date. A key can be valid for at most one year.
7. Select Create.
8. Copy the generated value immediately and store it in a secrets manager. The complete key is shown only once.

An expired or inactive key cannot be used for integration login. Deleting a key in the UI marks it inactive; it is not physically removed from storage.

Part 2 - Authenticate the client application

Endpoint

POST {COLROWS_BASE_URL}/api/integration/login
Content-Type: application/json
Accept: application/json

Request

{
  "userName": "developer@example.com",
  "pwd": "user-password",
  "apiKey": "CLIENT_INTEGRATION_KEY"
}

The endpoint does not require a Cloudflare Turnstile token. It validates the user credentials and confirms that apiKey belongs to the user's organization, is active, and has not expired.

Backend JavaScript example

async function getColrowsToken(userName, password, apiKey) {
  const response = await fetch(
    "https://cloud.colrows.com/api/integration/login",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/json"
      },
      body: JSON.stringify({ userName, pwd: password, apiKey })
    }
  );

  const body = await response.json();
  if (!response.ok) {
    throw new Error(body.message || "Colrows integration login failed");
  }
  return body.payload;
}

Successful response

{
  "payload": {
    "token": "eyJ...",
    "timeToLive": 1786450000000,
    "authorizedAs": "USER",
    "user": {
      "userId": "developer@example.com"
    }
  }
}

Use payload.token as the raw embed token. For ordinary API calls, send Authorization: Bearer TOKEN.

Part 3 - Embed an AI Assistant

Configure an assistant

1. Open Administration → AI Assistants.
2. Select Add Assistant.
3. Enter a unique name.
4. Select the datasource the assistant must use. This binding is required for embedded chat.
5. Optionally select a schema. Schema selection is not required.
6. Optionally provide styling configuration, then save.
7. Use the assistant's How to Use action to obtain its assistant ID and embed examples.

If the assistant API returns datasource: null, edit the assistant and bind an active datasource. Otherwise embedded chat shows Please select datasource to proceed.

AI Assistant iframe

<iframe
  id="colrows-assistant"
  title="Colrows AI Assistant"
  width="100%"
  height="700"
  frameborder="0"
  allow="clipboard-write"
  style="border: 0; border-radius: 8px;">
</iframe>
<script>
  const url = new URL(
    `/chat/${encodeURIComponent(assistantId)}`,
    "https://cloud.colrows.com"
  );
  url.searchParams.set("theme", "light");
  url.searchParams.set("token", colrowsToken);
  document.querySelector("#colrows-assistant").src = url.toString();
</script>

AI Assistant JavaScript loader

<div id="colrows-assistant" data-assistant-id="ASSISTANT_ID"></div>
<script src="https://cloud.colrows.com/embed.js"></script>
<script>
  AssistantChat.init({
    containerId: "colrows-assistant",
    baseUrl: "https://cloud.colrows.com",
    theme: "light",
    token: colrowsToken
  });
</script>

Part 4 - Embed a Dashboard

Open the dashboard's action menu and select Embed to obtain its dashboard ID and integration examples.

Choose the access mode

Public dashboard iframe

<iframe
  src="https://cloud.colrows.com/embed/dashboard/DASHBOARD_ID?theme=light&access=public"
  title="Colrows Dashboard"
  width="100%"
  height="800"
  frameborder="0"
  style="border: 0;">
</iframe>

If the dashboard is not enabled for public sharing, this embed fails rather than falling back to authenticated access.

Restricted dashboard iframe

<iframe
  id="colrows-dashboard"
  title="Colrows Dashboard"
  width="100%"
  height="800"
  frameborder="0"
  style="border: 0;">
</iframe>
<script>
  const url = new URL(
    `/embed/dashboard/${encodeURIComponent(dashboardId)}`,
    "https://cloud.colrows.com"
  );
  url.searchParams.set("theme", "light");
  url.searchParams.set("access", "authenticated");
  url.searchParams.set("token", colrowsToken);
  document.querySelector("#colrows-dashboard").src = url.toString();
</script>

Dashboard JavaScript loader

<div id="colrows-dashboard" data-dashboard-id="DASHBOARD_ID"></div>
<script src="https://cloud.colrows.com/dashboard-embed.js"></script>
<script>
  DashboardEmbed.init({
    containerId: "colrows-dashboard",
    baseUrl: "https://cloud.colrows.com",
    theme: "light",
    // Omit token only when the dashboard is public.
    token: colrowsToken
  });
</script>

The loader selects authenticated mode when token is present and public mode when it is omitted.

Part 5 - Token lifecycle and security

• Obtain tokens on a trusted client backend.
• Never expose the username, password, or API key in frontend code.
• Treat the session token as a credential even though it is removed from the visible iframe URL.
• Colrows uses the supplied token directly; it does not exchange it for another token.
• The same active token may be used across multiple assistant and dashboard embeds.
• The client is responsible for obtaining and distributing a new token when the current token expires.
• Use HTTPS for both Colrows and the embedding application.
• Do not log complete iframe URLs containing tokens.
• Restrict production frame-ancestors to approved client origins where possible.
• Public dashboards expose their rendered content to anyone with the URL.

Part 6 - Troubleshooting

Integration checklist

• Create an active API key and store its one-time value securely.
• Call /api/integration/login from the client backend using apiKey.
• Extract the raw value of payload.token.
• For an assistant, confirm its datasource binding and obtain its assistant ID.
• For a dashboard, obtain its dashboard ID and decide public or restricted access.
• Supply a token for every AI Assistant and restricted Dashboard embed.
• Omit the token only for a dashboard explicitly enabled for public sharing.
• Renew tokens from the client application when they expire.
• Confirm production origin, framing, permissions, and secret-handling policies.