Embed

Embedding lets you keep users inside your product while still using Boarbs for feedback collection, voting, and discussion.

How Embed Works

1. Your backend creates an embed session with an organization API key
2. Boarbs returns a signed embedUrl
3. Your frontend renders that URL inside an <iframe>

1. Create an Organization API Key

Go to Settings → API and create an organization-scoped API key.

Use a read-write key if your integration needs to create embed sessions.

BOARBS_API_KEY=sk_...
BOARBS_BOARD_ID=your_board_id

2. Create an Embed Session on Your Backend

Never create embed sessions from client-side code. Keep your API key on the server.

const response = await fetch("https://YOUR_BOARBS_DOMAIN/api/embed/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOARBS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    boardId: process.env.BOARBS_BOARD_ID, // optional, but recommended when you have multiple public boards
    userId: user.id,
    email: user.email,
    firstName: user.firstName,
    lastName: user.lastName,
    avatarUrl: user.avatarUrl,
    plan: user.plan,
    metadata: {
      accountId: user.accountId,
    },
    expiresInSeconds: 604800,
  }),
});

const { embedUrl, sessionToken, portalLoginUrl } = await response.json();

portalLoginUrl is the hosted portal with ?sso= already attached. Use it when a user should leave the iframe and continue on your-workspace.boarbs.com as the same person. The token is the same sessionToken the widget and iframe already use.

YOUR_BOARBS_DOMAIN is the domain where Boarbs itself is running. It is not the page in your app that will contain the iframe. On Boarbs Cloud this is usually a Boarbs-hosted workspace URL such as acme.boarbs.com. On self-hosted setups it is your own Boarbs domain.

Request Fields

The board must either be public or belong to the same organization as the API key. If you omit boardId, the fallback only considers public boards.

Identity Behavior

When you pass both userId and email, Boarbs treats userId as the primary identity and uses email as a fallback.

That means:

• use a stable userId from your own system whenever possible
• keep sending email as well when you have it, especially for compatibility and notifications
• do not rely on email alone if your users can change their address later

For returning users, send the same userId again when you create a new embed session. This keeps actions such as existing votes tied to the same person even if their email changes.

avatarUrl is optional. If you pass it, Boarbs can show the user's avatar in identified embed and widget experiences. If privacy is a concern, prefer a first-party or proxied image URL instead of a third-party avatar host.

Creating an embed session does not create a portal sign-in account by itself. To log that same person into the hosted portal, send them to portalLoginUrl or add ?sso=SESSION_TOKEN to a portal link. See Automatic Login.

3. Render the Iframe on the Frontend

<iframe
  src="EMBED_URL_FROM_BACKEND"
  width="100%"
  height="700"
  frameborder="0"
  title="Feedback"
></iframe>

React Example

"use client";

import { useEffect, useState } from "react";

export function FeedbackEmbed() {
  const [embedUrl, setEmbedUrl] = useState<string | null>(null);

  useEffect(() => {
    fetch("/api/feedback-embed-url")
      .then((response) => response.json())
      .then((data) => setEmbedUrl(data.embedUrl));
  }, []);

  if (!embedUrl) {
    return <div>Loading feedback…</div>;
  }

  return (
    <iframe
      src={embedUrl}
      width="100%"
      height="700"
      frameBorder="0"
      title="Feedback"
    />
  );
}

Optional URL Parameters

You can pass filters on the embed URL, for example:

https://YOUR_BOARBS_DOMAIN/embed?token=TOKEN&status=planned&sortBy=mostVoted&search=dark+mode

Common parameters include:

• status
• search
• sortBy
• tags

Security Notes

• never expose your Boarbs API key in browser code
• treat embed session URLs like credentials
• use HTTPS in production
• set a shorter expiresInSeconds value if you want tighter session control

Note on the API Explorer

The embed session flow exists as an API integration, but it is not currently part of the public explorer at /api/docs.

Use the API guide for the integration model, and use this page for the actual embed session workflow.

When to Use Embed

Embed is a good fit when:

• your product already has authentication
• you want feedback to live inside your app
• you want to pass user identity from your own backend

If you want the fastest no-code launch, use the Portal instead.

Next Steps

• Automatic Login — Log the same embed user into the hosted portal
• Portal — Use the hosted feedback portal instead of embedding
• Permissions and Visibility — Understand how embed access differs from portal access
• Troubleshooting — Debug session scope, permissions, and silent failures
• API — Understand what the explorer covers and where embed fits outside it
• Getting Started — Review the default workspace setup first