API reference
The public surface of
@thunderid/nextjs, as documented in its reference pages.<ThunderIDProvider />The `ThunderIDProvider` is a React Server Component that initializes ThunderID authentication and wraps your application layout. It manages server-side session state and provides authentication context to all child components.
childrenReactNode**Required.** Your application tree
sessionCookieExpiryTimenumberSession cookie lifetime in seconds. Also configurable via the `THUNDERID_SESSION_COOKIE_EXPIRY_TIME` environment variable
import { ThunderIDProvider } from '@thunderid/nextjs/server'export default function RootLayout({children,}: {children: React.ReactNode}) {return (<html lang="en"><body><ThunderIDProvider>{children}</ThunderIDProvider></body></html>)}
ConfigurationThe ThunderID Next.js SDK reads configuration primarily from environment variables. This keeps secrets out of your source code and follows Next.js conventions.
NEXT_PUBLIC_THUNDERID_BASE_URL=https://localhost:8090NEXT_PUBLIC_THUNDERID_CLIENT_ID=<your-client-id>THUNDERID_CLIENT_SECRET=<your-client-secret>THUNDERID_SECRET=<a-random-secret-for-session-signing>
MiddlewareThe ThunderID Next.js SDK provides Edge Runtime-compatible middleware for automatic token refresh and route protection.
import {thunderIDProxy,createRouteMatcher,} from '@thunderid/nextjs/server'const isProtectedRoute = createRouteMatcher(['/dashboard(.*)'])export default thunderIDProxy(async (thunderid, request) => {if (isProtectedRoute(request)) {await thunderid.protectRoute()}})export const config = {matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],}
Server ActionsThe ThunderID Next.js SDK provides server actions for authentication, session management, and user operations. These run only on the server and never expose tokens to the client. Import all server actions from `@thunderid/nextjs/server`.
(await thunderid()).getAccessibleOrganizationUnits(options?)Promise<AccessibleOrganizationUnitList>Lists the organization units the signed-in user can access, from `/users/me/ous`, with the access token of the request's session. `scope: 'siblings'` narrows the list to the accessible units that share the parent of the current unit; `limit` and `offset` page it.
import { signInAction } from '@thunderid/nextjs/server'// Redirect-based sign-in (default)await signInAction()// With embedded flow payload (advanced)await signInAction(payload, requestConfig)
useThunderID()The `useThunderID` hook gives client components the ThunderID context that `ThunderIDProvider` sets up. Import it from `@thunderid/nextjs`. The organization unit members are listed below.
currentOrganizationUnitCurrentOrganizationUnit | nullThe organization unit the session was issued for, read on the server from the `ouId`, `ouHandle`, and `ouName` claims of the session's access token, for display only, or `null`.
getCurrentOrganizationUnit()Promise<CurrentOrganizationUnit | null>Reads the current organization unit from the session's access token again.
switchOrganizationUnit(organizationUnitId, options?)Promise<User | undefined>Signs in again bounded to another organization unit through a server action. Redirect mode sends the browser to `{baseUrl}/ou/{ouId}/oauth2/authorize`, and the callback replaces the session; `{ redirect: false }` always fails with `InteractionRequired`. Embedded mode runs an `AUTHENTICATION` flow with `ouId` and replaces the session cookie in place. A failed switch keeps the previous session and rejects with a code from `OrganizationUnitSwitchErrorCodes`.
'use client'import { useThunderID } from '@thunderid/nextjs'export default function CurrentOrganization() {const { currentOrganizationUnit } = useThunderID()return <p>Working in {currentOrganizationUnit?.name}</p>}
<OrganizationUnitSwitcher />The `OrganizationUnitSwitcher` component shows the organization unit the session is in, in a field that opens a menu of the units the signed-in user can access. It reads the units from `/users/me/ous` through a server action, so the access token stays on the server, and switches through `switchOrganizationUnit` from `useThunderID()`. A failed switch keeps the session as it was and shows a translated message under the field.
scopeoptionalAccessibleOrganizationUnitScope`'siblings'` lists the accessible units that share the parent of the current unit. Omit it to list every accessible unit.
limitoptionalnumberThe page size. Defaults to `10`.
onSwitchoptional(unit: AccessibleOrganizationUnit, user: User) => voidCalled with the unit and the refreshed user after a switch that completes in place. A switch that leaves the page completes on the callback instead.
onSelectoptional(unit: AccessibleOrganizationUnit) => voidTakes over a pick: called with the unit instead of switching.
onErroroptional(error: unknown) => voidCalled when a switch or a load fails. The component shows its message either way.
switchOptionsoptionalSwitchOrganizationUnitOptionsOptions passed to `switchOrganizationUnit`. Only `redirect` applies.
titleoptionalstringOverrides the small label above the current unit. Pass an empty string to omit it.
classNameoptionalstringAdditional CSS class names.
preferencesoptionalPreferencesComponent-level preference overrides, including i18n.
childrenoptional(props: OrganizationUnitSwitcherRenderProps) => ReactNodeRender function that replaces the built-in UI.
'use client'import { OrganizationUnitSwitcher, SignedIn } from '@thunderid/nextjs'function Header() {return (<header><SignedIn><OrganizationUnitSwitcher scope="siblings" /></SignedIn></header>)}export default Header