Automatic Login

Automatic login takes the identity you already send to the widget or embed and starts a hosted portal session for that same person.

It does not replace workspace SSO. It also does not log organization admins or other team members into the portal.

What it solves

Widget and embed sessions already know userId, email, and name. Opening your-workspace.boarbs.com used to treat that visitor as a guest.

Automatic login closes that gap. The same signed embed session can:

• create a portal end-user if one does not exist
• start a portal session for that person
• keep votes, comments, and posts attached to the same email

How it works

1. Your backend creates an embed session with an organization API key. That is the same POST /api/embed/sessions call used by the widget and iframe embed.
2. The response includes sessionToken and portalLoginUrl.
3. Send people to the hosted portal with ?sso=SESSION_TOKEN, or let the widget attach that parameter to portal links.
4. Boarbs validates the session, refuses team-member emails, and sets a portal session cookie.

The token is the existing embed session token. The identity fields are the same shape you already send: userId, email, firstName, lastName, and avatarUrl.

1. Create the signed session on your backend

Never create the session in browser code. Keep the 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,
    userId: user.id,
    email: user.email,
    firstName: user.firstName,
    lastName: user.lastName,
    avatarUrl: user.avatarUrl,
    expiresInSeconds: 604800,
  }),
});

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

email is required for automatic login. Boarbs uses it to create or find the portal user. Keep sending a stable userId as well so widget and embed identity stay consistent.

2. Link to the hosted portal

Use the returned portalLoginUrl, or append sso to any portal deep link:

https://your-workspace.boarbs.com/?sso=SESSION_TOKEN
https://your-workspace.boarbs.com/roadmap?sso=SESSION_TOKEN
https://your-workspace.boarbs.com/p/post-slug?sso=SESSION_TOKEN

Treat these URLs like credentials. Prefer short expiresInSeconds values when you put the token in a query string.

3. Widget links

If the widget is identified with sessionToken, it attaches sso to links that point at the widget origin (your workspace portal).

window.Boarbs.init({
  workspace: "acme",
  sessionToken,
});

// Build a portal URL yourself:
const roadmapUrl = window.Boarbs.portalUrl("/roadmap");

The widget iframe also stores the session in a cookie on the workspace domain. Visiting the portal on that same host can reuse the cookie when ?sso= is missing.

What automatic login will not do

• It will not sign in organization owners, admins, or other team members. Those people keep using normal workspace login.
• It will not create a team membership or grant /app access.
• It will not accept a session with no email.
• It will not accept a session that belongs to a different workspace.

If the token is missing, expired, or refused, the visitor stays a guest on the public portal.

Security notes

• create sessions only on your server
• never put the Boarbs API key in browser code
• do not log admins in this way
• prefer HTTPS in production
• strip sso from analytics and server logs when you can

This is not SAML or OIDC. Those remain out of scope for this flow.

Next steps

• Embed — Create the session used by both the iframe and automatic login
• Widget — Identify the user inside your product
• Portal — Where the hosted session is used
• Deep Links — Add sso to a specific post or roadmap URL
• Permissions and Visibility — End-users vs team members