iblai-vibe-auth

/iblai-vibe-auth

Add ibl.ai SSO authentication to a vanilla Next.js app. After completion, unauthenticated users are redirected to login.iblai.app and returned with a session -- no API tokens to manage.

Templates: the auth files this skill creates (providers, store, SSO callback, lib/iblai/*) are bundled here as Jinja2 assets — assets/. You render them into the project in Step 3. See /iblai-vibe-scaffold for the {{ }} variable contract and the shared patch mechanics.

If .env.local already has NEXT_PUBLIC_MAIN_TENANT_KEY set to a real value (not a placeholder like your-main-platform, your-tenant, your-platform, your-tenant-key, test-tenant, main, or empty), keep that value.

Common setup (brand, conventions, env files, verification): see docs/skill-setup.md.

Which sign-in architecture? (read first)

Sign-in is the same hosted round trip for every ibl.ai front end (login.<domain>/login?app=…&redirect-to=<origin>&tenant=<org> → back to /sso-login-complete?data=…); what differs is where the org comes from. /iblai-vibe-start records the answer in iblai.env as ARCHITECTURE=; if it is missing, ask one question before writing files:

`ARCHITECTURE`	The app is for	Org key	This skill does
`single-org` (default)	members of one organization — yours, or the customer you deploy to	pinned: `NEXT_PUBLIC_MAIN_TENANT_KEY` (never `main`)	everything below as written
`multi-org`	users who belong to many organizations (the os.ibl.ai model)	from the URL (`/platform/[org]/…`) plus a switcher; `NEXT_PUBLIC_MAIN_TENANT_KEY=main` is the community org	everything below, then Going multi-org at the end
`headless`	nobody signs in — scripts, CI, a backend	`IBLAI_ORG` per call	not this skill: `/iblai-api-login` and the `iblai-api-*` family

The parameters, tokens, anonymous access, organization switching, native shells, and the OS's implementation are in docs/auth-model.md.

Step 0: Start from vibe-starter? (new projects)

Before running this skill, ask the user:

Are you starting a new project from scratch? If so, vibe-starter (https://github.com/iblai/vibe/tree/main/skills/start/iblai-vibe-ops-init/assets/vibe-starter) is a pre-wired Next.js 16 + Tailwind v4 + shadcn/ui template with ibl.ai SSO auth, a responsive navbar, and profile/account/notifications pages already in place. Want to use that instead?

If yes, copy the bundled starter template from the installed iblai-vibe-ops-init skill's assets/vibe-starter/ directory (a sibling of this skill's directory), or fetch it from the vibe repo if those assets are not installed -- tell the user which path you took:

cp -a <skills-dir>/iblai-vibe-ops-init/assets/vibe-starter/. .
# or, without local assets:
git clone --depth 1 https://github.com/iblai/vibe.git vibe-tmp && cp -a vibe-tmp/skills/start/iblai-vibe-ops-init/assets/vibe-starter/. . && rm -rf vibe-tmp

pnpm install --ignore-scripts

Run with --ignore-scripts to skip package lifecycle (postinstall) scripts.

If they prefer to wire auth into an existing app, continue below.

Prerequisites

Want a complete app from scratch? Use vibe-starter (Step 0 above) — it ships with auth, a navbar, and profile/account/notifications already wired, so you can skip this skill. For the underlying whole-app scaffold and its templates, see /iblai-vibe-scaffold.

This skill adds auth to a vanilla Next.js app or an existing project by creating the auth files directly (Step 3).

Next.js 14+ with App Router (app/ directory)
Node.js 18+

Step 1: Check Environment

Before proceeding, check for a iblai.env in the project root. Look for PLATFORM, DOMAIN, and TOKEN variables. If the file does not exist or is missing these variables, tell the user: "You need an iblai.env with your platform configuration. Copy the bundled template and fill in your values: cp iblai.env.example iblai.env (vibe-starter ships the example) — or, when the project has no iblai.env.example: curl -o iblai.env https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/iblai.env"

If PLATFORM is set to a real value (not your-platform or your-main-platform), use it as the platform key in Step 3. Otherwise use the placeholder and tell the user to replace it.

Step 2: Customize Auth Interface

STOP here. You MUST ask the user these questions before proceeding to Step 3. Do NOT skip this step.

How

Fetch the org's platform_name (GET https://api.{domain}/dm/api/core/orgs/{platform}/metadata/), ask the user what the app does and whether they want the navbar, generate a headline and tagline, save the AUTH_* values to iblai.env, STOP for the user to review, then upload the logo (POST …/platforms/{platform}/public-image-assets/, three categories) and PUT auth_web_skillsai + auth_web_mentorai into the org metadata. The exact questions, defaults, upload table, and JSON payload are in references/auth-interface.md — follow it verbatim. Never drop the org's other metadata keys (GET, merge, PUT — see /iblai-vibe-org-metadata).

Step 3: Create the auth files

Render the bundled assets/ Jinja2 templates into the project — strip the .j2 suffix and substitute {{ platform_key }} with the platform key. For a src/ layout, place files under src/lib, src/store, src/providers accordingly.

Template (`assets/…`)	Destination
`config.ts.j2`	`lib/iblai/config.ts`
`auth-utils.ts.j2`	`lib/iblai/auth-utils.ts`
`storage-service.ts.j2`	`lib/iblai/storage-service.ts`
`tenant.ts.j2`	`lib/iblai/tenant.ts`
`iblai-store.ts.j2`	`store/iblai-store.ts`
`iblai-providers.tsx.j2`	`providers/iblai-providers.tsx`
`iblai-styles.css.j2`	`app/iblai-styles.css`
`sso-login-complete-page.tsx.j2`	`app/sso-login-complete/page.tsx`

Then apply the project patches (each is idempotent — check for a marker before editing; full mechanics in /iblai-vibe-scaffold → add-command):

next.config — add the @reduxjs/toolkit webpack resolve.alias that deduplicates RTK. Without it the SDK binds a different ReactReduxContext and RTK Query hooks silently return undefined.
globals.css — add @import "./iblai-styles.css";.
.env.local — set NEXT_PUBLIC_MAIN_TENANT_KEY=<platform key> (← PLATFORM) and, for server-side platform calls, IBLAI_API_KEY (← TOKEN). Nothing else needs deriving — the URL vars default in the rendered lib/iblai/config.ts.

The SSO callback at app/sso-login-complete/page.tsx must stay outside the providers (Step 5 / Troubleshooting), or it deadlocks on login.

Step 4: Install Dependencies and Add Test Script

Add the SDK dependencies and install:

pnpm add @iblai/iblai-js @reduxjs/toolkit react-redux sonner lucide-react
pnpm install --ignore-scripts

Run with --ignore-scripts to skip package lifecycle (postinstall) scripts.

These are:

@iblai/iblai-js -- SDK (auth, data layer, UI components)
@reduxjs/toolkit + react-redux -- state management (SDK uses RTK Query)
sonner -- toast notifications
lucide-react -- icons

If package.json does not already have a "test" script (or it still has the default create-next-app placeholder), add vitest:

pnpm add -D vitest

Then set the test script in package.json:

"scripts": {
  "test": "vitest run"
}

Step 5: Wire Providers into Layout

Open app/layout.tsx and wrap {children} with the generated IblaiProviders. Add viewport-fit=cover to the metadata so mobile builds (iOS/Android) respect safe area insets and don't overlap with the status bar.

If you have no existing providers:

import type { Metadata, Viewport } from "next";
import { IblaiProviders } from "@/providers/iblai-providers";

export const metadata: Metadata = {
  title: "My App",
};

export const viewport: Viewport = {
  width: "device-width",
  initialScale: 1,
  viewportFit: "cover",
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <IblaiProviders>{children}</IblaiProviders>
      </body>
    </html>
  );
}

If you have existing providers (e.g., custom contexts):

import type { Metadata, Viewport } from "next";
import { IblaiProviders } from "@/providers/iblai-providers";
import { MyProvider } from "./my-provider";

export const metadata: Metadata = {
  title: "My App",
};

export const viewport: Viewport = {
  width: "device-width",
  initialScale: 1,
  viewportFit: "cover",
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <IblaiProviders>
          <MyProvider>
            {children}
          </MyProvider>
        </IblaiProviders>
      </body>
    </html>
  );
}

IblaiProviders must be the outermost provider -- it contains Redux, Auth, and Organization providers that other components depend on. Place your own providers inside it.

Step 6: Configure Environment

Step 3 created .env.local with the platform key. Verify it has the right value (edit the line directly if not):

NEXT_PUBLIC_MAIN_TENANT_KEY=your-main-platform

The API URLs default to hosted iblai.app in the rendered lib/iblai/config.ts; override them in .env.local only when self-hosting.

Step 7: Import SDK Styles

Verify app/globals.css has the SDK imports (Step 3 adds these):

@import '@iblai/iblai-js/web-containers/styles';
@source "../node_modules/@iblai/iblai-js/dist/web-containers/source";

If these lines are missing, add them near the top of globals.css.

Step 8: Replace Default Home Page

After adding auth, check if app/page.tsx still has the default Next.js content (look for next/image, vercel.svg, Vercel, or Get started by editing). If it does, replace it with the ibl.ai home page — render assets/home-page.tsx.j2 into app/(app)/page.tsx (or app/page.tsx), substituting {{ }} placeholders.

If the user has already customized their home page, skip this step.

Step 9: Navbar

If the user said yes to the navbar question in Step 2, run /iblai-vibe-navbar now before starting the dev server.

Step 10: Start Dev Server

Start the dev server so the user can see the result:

pnpm dev

Open http://localhost:3000
You should be redirected to https://login.iblai.app
Log in (or create a free account)
You'll be returned to your app with a fully authenticated session
Check browser localStorage -- you should see axd_token, userData, tenants

What Was Generated

File	Purpose
`app/sso-login-complete/page.tsx`	SSO callback -- stores tokens from URL into localStorage
`lib/iblai/config.ts`	Environment variable accessors (API URLs, platform key, auth URL)
`lib/iblai/storage-service.ts`	localStorage wrapper implementing the SDK's StorageService interface
`lib/iblai/auth-utils.ts`	`redirectToAuthSpa()`, `hasNonExpiredAuthToken()`, `handleLogout()`
`store/iblai-store.ts`	Redux store with `coreApiSlice`, `mentorReducer`, `mentorMiddleware`, and the slice keys the SDK `<Chat>` hard-codes (`chat`, `chatInput`, `chatSliceShared`, `files`, `rbac`, `subscription`, `topBanner`)
`providers/iblai-providers.tsx`	Provider chain: ReduxProvider > AuthProvider > TenantProvider

What Was Patched

next.config.ts -- webpack resolve.alias to deduplicate @reduxjs/toolkit, turbopack: {} for Next.js 16+. Without the dedup, SDK components use a different ReactReduxContext and RTK Query hooks silently return undefined with zero HTTP requests.
globals.css -- SDK base styles import.
.env.local -- platform key (NEXT_PUBLIC_MAIN_TENANT_KEY) and, for server-side platform calls, IBLAI_API_KEY.

Advanced: Route Groups

For production apps, consider moving the SSO callback outside the auth providers using Next.js route groups:

app/
├── (auth)/
│   └── sso-login-complete/page.tsx   ← Outside providers (no AuthProvider wrapper)
└── (app)/
    ├── layout.tsx                     ← IblaiProviders wraps only this group
    └── page.tsx

This prevents the SSO callback deadlock where AuthProvider blocks rendering before tokens are stored. Step 3 places the callback at app/sso-login-complete/ (flat, no route group) which works for simple apps.

For the route group pattern, see the vibe-starter reference app: https://github.com/iblai/vibe/tree/main/skills/start/iblai-vibe-ops-init/assets/vibe-starter

Troubleshooting

Sign-in redirects to login.iblai.app and never comes back

Every origin the app runs on — http://localhost:3000, the deployed URL, a Tauri custom scheme — must be in the organization's allowed redirect origins. Nothing in the app can fix this; ask your ibl.ai operator to add the origin. Also check the org key is not main (the shared org) or a placeholder — the starter renders an alert for those instead of looping.

"Unknown server error" with custom-domains on localhost

The SDK calls /api/custom-domains?domain=localhost as part of platform detection. This fails on localhost but is harmless -- the platform is resolved from NEXT_PUBLIC_MAIN_TENANT_KEY in .env.local instead. You can safely ignore this console error during local development.

SDK components show undefined / no API requests

@reduxjs/toolkit must be deduplicated in next.config.ts. Without the webpack alias, the SDK's components use a different ReactReduxContext than your app's StoreProvider, so RTK Query hooks silently return undefined.

Verify your next.config has:

config.resolve.alias['@reduxjs/toolkit'] = rtkDir;

Auth redirect loops

The SSO callback page (app/sso-login-complete/page.tsx) must NOT be wrapped by AuthProvider. If it is, AuthProvider detects "no tokens" and redirects to login before the callback can store the tokens -- creating an infinite loop.

If this happens, use the route group pattern described above to separate the SSO callback from the authenticated routes.

Blank screen after login

Check that .env.local has NEXT_PUBLIC_MAIN_TENANT_KEY set. Without it, the platform resolution falls back to custom-domain detection which fails on localhost, leaving the app in a broken state.

Next Steps

After auth is set up, add more features using skills -- ask your AI assistant to use:

Skill	What It Adds
`/iblai-vibe-agent-chat`	In-process agent chat surface
`/iblai-vibe-profile`	User profile dropdown + settings page
`/iblai-vibe-account`	Account/organization settings page
`/iblai-vibe-analytics`	Analytics dashboard page
`/iblai-vibe-notification`	Notification bell + center page

For a complete reference app with auth, navbar, and pages already wired: https://github.com/iblai/vibe/tree/main/skills/start/iblai-vibe-ops-init/assets/vibe-starter

Brand guidelines: BRAND.md

Going multi-org (`ARCHITECTURE=multi-org`)

Five moves, all with SDK pieces vibe-starter already imports — the full version is providers/index.tsx in iblai/os:

Org in the URL — app/platform/[tenantKey]/…; read it with useParams(); keep resolveAppTenant() for the default org.
Providers — TenantProvider currentTenant={stored} requestedTenant={fromRoute} with saveUserTokens, saveUserTenants, saveCurrentTenant, saveTenant implemented (the starter's iblai-providers.tsx already has them).
Switching — UserProfileDropdown showTenantSwitcher (or TenantSwitcher) → handleTenantSwitch(org, { authUrl }) from @iblai/iblai-js/web-utils: clears storage, re-enters the SPA with tenant=, broadcasts to other tabs.
Anonymous per agent — in AuthProvider's middleware, for ^/platform/([^/]+)/([^/]+) fetch the agent's public settings (useLazyGetMentorPublicSettingsQuery) and return false when allow_anonymous or mentor_visibility === "viewable_by_anyone".
Landing path guard — after SSO, reset to / when the stored path names an org other than the one just authenticated (resolveRedirectPath on SsoLogin).