Skip to main content
Always provide onSessionExpired. Without it, users whose refresh token expires will be silently stuck — no redirect, no error, just a broken app state.

​
Quick setup

Wrap your app (or its authenticated subtree) with AilitaProvider. It handles tenant discovery, theme injection, and token refresh automatically. 
// app/providers.tsx
// 'use client' is required — AilitaProvider uses React context and useEffect,
// which are only available in Client Components.
'use client'

import { AilitaProvider } from 'ailita-library'
import 'ailita-library/styles'
import { useRouter } from 'next/navigation'

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter()

  return (
    <AilitaProvider
      clientId="pk_live_your_client_id"
      baseUrl="https://api.yourdomain.com/api/v1"
      onSessionExpired={() => router.push('/login')}
      loadingFallback={<div>Loading...</div>}
      errorFallback={<div>Failed to load tenant. Please refresh.</div>}
    >
      {children}
    </AilitaProvider>
  )
}

​
Props

​
clientId
string
required
Public client key for this tenant (e.g. "pk_live_abc123"). Used as the primary lookup key in GET /auth/discovery?clientId= on mount. The backend validates this against a registered domain allowlist using the browser-supplied Origin header. Changing this prop re-runs discovery.
​
slug
string
Merchant subdomain slug (e.g. "sanfernando"). Optional — sent alongside clientId for audit logging on the backend. Not used as a security identifier.
​
baseUrl
string
required
Base URL of the API, e.g. https://api.yourdomain.com/api/v1. Set once before discovery runs. All subsequent API calls use this base URL.
​
onSessionExpired
() => void
Called when the refresh token is invalid and tokens are cleared. Redirect to /login here. Treat as required — without it, users silently lose their session with no recovery path. The 401 refresh queue in client.ts fires this callback after a failed refresh attempt.
​
loadingFallback
ReactNode
default:"null"
Rendered while discovery is in progress. Defaults to null (blank screen). Provide a spinner or skeleton to avoid a content flash on mount.
​
errorFallback
ReactNode
default:"null"
Rendered if discovery fails (network error, unknown slug). Defaults to null. Provide an error state that prompts the user to refresh or contact support.

​
How discovery works

On mount, AilitaProvider runs the following sequence:
  1. Sets the Axios base URL to your baseUrl prop
  2. Calls GET /auth/discovery?clientId={clientId} to fetch tenant configuration
  3. Receives tenant data: name, colors, loginMode, signupMode, publicApiKey
  4. Injects X-App-ID and X-Mid-Key headers into all subsequent API requests via an Axios interceptor
The backend uses clientId to look up the tenant and validates the request Origin header against that tenant’s registered domain allowlist. Auth requests from unregistered domains are rejected with 403. This is the primary defense against tenant impersonation.

​
Internal composition

AilitaProvider composes three layers internally. Consumers never need to instantiate ThemeProvider or AuthProvider directly. 
AilitaProvider           -- discovery + tenant config
  ThemeProvider          -- CSS variables (--color-primary, --color-secondary)
    AuthProvider         -- auth state + silent token refresh on mount
      {children}

​
loginMode and signupMode

Your tenant’s loginMode and signupMode are returned by the discovery endpoint and control which UI flows LoginForm and SignupForm render.

​
loginMode

ValueBehavior
PASSWORDStandard email + password login
OTP_EMAILLogin via one-time code sent to email (no password)
PASSWORD_OR_OTP_EMAILUser chooses between password or email OTP

​
signupMode

ValueBehavior
OPENAnyone can register
INVITATION_ONLYRegistration requires an invitation link
These values are returned by the discovery endpoint and set automatically. Your tenant’s loginMode and signupMode are configured in the ailita backend admin panel — you do not need to pass them as props.

​
Next steps

Protect routes with AuthGuard

Require authentication or specific roles before rendering protected UI.