Authentication

Login, refresh, SSO, and token stores with @lunnoa/client.

Use @lunnoa/client auth helpers so Pattern B apps do not reinvent login, refresh, or token storage. Pattern A (API keys) still uses createServerClient or apiKey on the constructor.

Choose a client factory

import { createBrowserClient, isLoginRequires2FA } from '@lunnoa/client';const lunnoa = createBrowserClient({  baseUrl: 'https://lunnoa.your-company.example',});const result = await lunnoa.auth.login({ email, password });if (isLoginRequires2FA(result)) {  await lunnoa.auth.verify2faLogin({    sessionToken: result.sessionToken,    token: totpOrBackupCode,  });}const me = await lunnoa.auth.me();

import { createServerClient } from '@lunnoa/client';const lunnoa = createServerClient({  baseUrl: process.env.LUNNOA_URL!,  apiKey: process.env.LUNNOA_API_KEY!,});

createBrowserClient defaults to localStorage keys accessToken and refreshToken (same keys as the built-in Automate UI). Pass createMemoryTokenStore() for Node scripts or tests.

For Pattern B in the browser, allow your origin with CORS_ALLOWED_ORIGINS on the deployment.

React hooks (@lunnoa/client/react)

Opt-in React helpers for Pattern B portals. Peer dependency: react ≥ 18. For the full hook set (progress, needs-input, agent chat, approvals, entities), see React hooks.

import { LunnoaAuthProvider, useLunnoaAuth } from '@lunnoa/client/react';import { isLoginRequires2FA } from '@lunnoa/client';export function App() {  return (    <LunnoaAuthProvider baseUrl={import.meta.env.VITE_LUNNOA_URL}>      <Shell />    </LunnoaAuthProvider>  );}function Shell() {  const { user, status, login, logout, error } = useLunnoaAuth();  if (status === 'loading') return <p>Loading…</p>;  if (!user) {    return (      <button        onClick={async () => {          const result = await login({ email, password });          if (isLoginRequires2FA(result)) {            // show TOTP form → verify2faLogin({ sessionToken, token })          }        }}      >        Sign in      </button>    );  }  return (    <div>      <p>{user.email}</p>      {error ? <p>{error}</p> : null}      <button onClick={() => logout()}>Sign out</button>    </div>  );}

More hooks (useExecutionProgress, useNeedsInput, useAgentChat, useApprovalsInbox, useEntityList) are documented in React hooks.

What lunnoa.auth wraps

Successful login helpers write camelCase tokens into the store (accessToken / refreshToken). Wire responses still use access_token / refresh_token.

Auto-refresh on 401

When a tokenStore is configured and autoRefresh is true (default for createBrowserClient), a 401 on an authenticated request triggers one POST /api/auth/refresh-token using the stored refresh token, then retries the original call. If refresh fails, the store is cleared.

You can still call auth.refresh() yourself (for example after catching LunnoaApiError.isUnauthorized when auto-refresh is off).

SSO for custom portals

1. Call auth.sso.listProviders() to render buttons (and to respect ssoEnforced / passwordAuthDisabled).
2. Navigate the browser to auth.sso.getLoginUrl(providerId).
3. The IdP callback hits Automate at /api/auth/sso/:providerId/callback, which redirects to CLIENT_URL/verify-token?token=… (the deployment's configured client URL, not an arbitrary custom origin).
4. Exchange the hidden token with auth.loginWithToken({ token }).

Token stores

import {
  createMemoryTokenStore,
  createLocalStorageTokenStore,
  LunnoaClient,
} from '@lunnoa/client';

const lunnoa = new LunnoaClient({
  baseUrl,
  tokenStore: createMemoryTokenStore(), // or createLocalStorageTokenStore()
});

Implement TokenStore yourself when tokens live in httpOnly cookies on your BFF: your store reads/writes via your backend; Lunnoa still receives Bearer JWTs.

Related

• TypeScript client SDK: overview and resource map
• API authentication: API keys, security notes
• Errors: 401 refresh mapping