Skip to main content

API reference

The public surface of

@thunderid/nextjs, as documented in its reference pages.

function<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.

Props
children
ReactNode

**Required.** Your application tree

sessionCookieExpiryTime
number

Session cookie lifetime in seconds. Also configurable via the `THUNDERID_SESSION_COOKIE_EXPIRY_TIME` environment variable

Example
import { ThunderIDProvider } from '@thunderid/nextjs/server'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>
<ThunderIDProvider>
{children}
</ThunderIDProvider>
</body>
</html>
)
}
functionConfiguration

The ThunderID Next.js SDK reads configuration primarily from environment variables. This keeps secrets out of your source code and follows Next.js conventions.

Example
NEXT_PUBLIC_THUNDERID_BASE_URL=https://localhost:8090
NEXT_PUBLIC_THUNDERID_CLIENT_ID=<your-client-id>
THUNDERID_CLIENT_SECRET=<your-client-secret>
THUNDERID_SECRET=<a-random-secret-for-session-signing>
functionMiddleware

The ThunderID Next.js SDK provides Edge Runtime-compatible middleware for automatic token refresh and route protection.

Example
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).*)'],
}
functionServer Actions

The 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`.

Organization Unit Methods
(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.

Example
import { signInAction } from '@thunderid/nextjs/server'
// Redirect-based sign-in (default)
await signInAction()
// With embedded flow payload (advanced)
await signInAction(payload, requestConfig)
hookuseThunderID()

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.

Organization Unit Members
currentOrganizationUnit
CurrentOrganizationUnit | null

The 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`.

Example
'use client'
import { useThunderID } from '@thunderid/nextjs'
export default function CurrentOrganization() {
const { currentOrganizationUnit } = useThunderID()
return <p>Working in {currentOrganizationUnit?.name}</p>
}
component<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.

Props
scopeoptional
AccessibleOrganizationUnitScope

`'siblings'` lists the accessible units that share the parent of the current unit. Omit it to list every accessible unit.

limitoptional
number

The page size. Defaults to `10`.

onSwitchoptional
(unit: AccessibleOrganizationUnit, user: User) => void

Called 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) => void

Takes over a pick: called with the unit instead of switching.

onErroroptional
(error: unknown) => void

Called when a switch or a load fails. The component shows its message either way.

switchOptionsoptional
SwitchOrganizationUnitOptions

Options passed to `switchOrganizationUnit`. Only `redirect` applies.

titleoptional
string

Overrides the small label above the current unit. Pass an empty string to omit it.

classNameoptional
string

Additional CSS class names.

preferencesoptional
Preferences

Component-level preference overrides, including i18n.

childrenoptional
(props: OrganizationUnitSwitcherRenderProps) => ReactNode

Render function that replaces the built-in UI.

Example
'use client'
import { OrganizationUnitSwitcher, SignedIn } from '@thunderid/nextjs'
function Header() {
return (
<header>
<SignedIn>
<OrganizationUnitSwitcher scope="siblings" />
</SignedIn>
</header>
)
}
export default Header
ThunderID LogoThunderID Logo

Product

DocsAPIsSDKs
© Copyright Linux Foundation Europe.For web site terms of use, trademark policy and other project policies please see https://linuxfoundation.eu/en/policies.