{message}
{details}
You are signed in.
Please sign in.
User ID: {userId}
{orgId &&Active org: {orgId}
} ``` It is cheap — no network call. The values come from the verified `__session` token. #### Fetching the full user with currentUser() `Astro.locals.currentUser()` makes a Backend API call to fetch the full user record. It deduplicates per request, so calling it multiple times in one render is safe: ```astro --- // src/pages/profile.astro const user = await Astro.locals.currentUser() if (!user) return Astro.redirect('/sign-in') ---Email: {user.emailAddresses[0]?.emailAddress}
``` #### Using the user object in .astro files The user object includes `firstName`, `lastName`, `emailAddresses`, `phoneNumbers`, `imageUrl`, `publicMetadata`, and `privateMetadata`. Public metadata is fine to render. Private metadata is server-only — never put it in HTML. > \[!WARNING] > `user.privateMetadata` is only available on the server-side `Backend User` object (the one returned by `currentUser()` or `clerkClient().users.getUser()`). It should never reach client JavaScript. Rendering it inline in `.astro` HTML leaks it to every visitor. ### Reading the current user on the client Client-side access comes from the `$userStore` nanostore. It updates reactively and works in any framework island: ```tsx // src/components/ClientGreeting.tsx import { useStore } from '@nanostores/react' import { $userStore } from '@clerk/astro/client' export default function ClientGreeting() { const user = useStore($userStore) if (user === undefined) return Loading... if (user === null) return Not signed in. return Hello, {user.firstName}. } ``` Mount with `client:load`. The initial `undefined` state is the loading state — always handle it, or you will flash signed-out UI while Clerk's JS initializes. ### Session tokens for backend API calls `getToken()` on the `auth()` object returns the current `__session` JWT. Use it when calling a separate backend service: ```ts // inside an .astro frontmatter or APIRoute handler const token = await Astro.locals.auth().getToken() const response = await fetch('https://api.example.com/tasks', { headers: { Authorization: `Bearer ${token}` }, }) ``` Token templates let you customize the claims for specific integrations: `getToken({ template: "supabase" })`. The external service verifies the token with Clerk's `verifyToken()` from `@clerk/backend`, or with any generic JWKS verifier pointed at your Frontend API's JWKS URL. ### Session expiry and refresh The `__session` token has a 60-second TTL and is auto-refreshed every 50 seconds. `BroadcastChannel` syncs sessions across browser tabs so a sign-out in one tab signs the user out everywhere. Force a refresh when you need fresh session claims (for example, after an out-of-band role change): ```ts const token = await Astro.locals.auth().getToken({ skipCache: true }) ``` Session maximum lifetime is a Clerk Dashboard setting. The default maximum is 7 days. Inactivity timeout is disabled by default; admins can enable it in the Dashboard. See [session options](/docs/guides/secure/session-options) for tuning. ## Working with organizations: building a multi-tenant dashboard This is the headline chapter for the dashboard use case. Organizations turn a single-tenant signup flow into a B2B-ready multi-tenant app without rolling your own schema. ### Why organizations matter for SaaS dashboards B2B SaaS users belong to multiple companies, teams, or projects. Each one is a tenant with its own members, roles, data, and (often) billing. Modeling that yourself — organizations table, memberships table, per-org roles, invitations, verified domains — is a multi-week project before you write a single business feature. Clerk's Organizations primitive gives you: - User-to-org memberships with roles. - Invitations (email, bulk, or link-based). - Verified domains (any user with `@yourcompany.com` auto-joins). - Enterprise SSO binding per organization. - An **active organization** concept — one org is active per session, synced across tabs via `BroadcastChannel`. ### Enabling organizations in Clerk Go to the Clerk Dashboard → **Organizations** → **Enable**. Organizations are part of Clerk's B2B feature set and are available on all paid plans. The base B2B tier includes: - 100 MROs in production, 50 MROs in development. - Up to 20 members per organization. - Built-in `org:admin` and `org:member` roles. - Basic RBAC with up to 10 custom roles per application. The **Enhanced B2B Authentication** add-on ($85/month annual, $100/month monthly) unlocks: - Unlimited members per organization. - Multiple custom Role Sets (the base tier ships a single Role Set). - Tiered MRO overages starting at $1/MRO and scaling down to $0.60/MRO at 100K+. - Verified domains with automatic invitations. - Linking enterprise SSO connections to specific organizations. MRO stands for [Monthly Retained Organization](/glossary#monthly-retained-organizations-mros) — an organization with at least 2 members where at least one is an MRU (Monthly Retained User). It is Clerk's B2B pricing metric and replaces MAU-style billing for organizations. > \[!NOTE] > Organizations are not available on the free Hobby plan. A paid plan (Pro or higher) is required to enable them in production. ### Adding the OrganizationSwitcher component The switcher is a dropdown that shows the user's current organizations and lets them switch, create, or leave. Drop it in the header: ```astro --- // src/layouts/DashboardHeader.astro import { OrganizationSwitcher, UserButton } from '@clerk/astro/components' ---You are a {orgRole} of this organization.
``` `clerkClient(Astro)` is the Backend API client. Unlike the Next.js factory (which is async), the Astro factory takes the `APIContext` (the `Astro` global in a page, `context` in an APIRoute) synchronously. Methods on the returned client are async and still need `await`. #### Filtering data by organization Every database query must scope to `locals.auth().orgId`. Do not trust `Astro.params.slug` as the sole source of truth — it is user-controlled input in the URL. The middleware sets the active org based on the URL via `organizationSyncOptions`, and the auth check above bounces users whose membership does not match. But application code should still do the belt-and-suspenders scoping: ```ts // src/lib/db.ts export async function listTasks(orgId: string) { return db.query( `SELECT id, title, status FROM tasks WHERE organization_id = $1 ORDER BY created_at DESC`, [orgId], ) } ``` Call it with `locals.auth().orgId`, never with `Astro.params.slug`. > \[!WARNING] > Using `Astro.params.slug` for data isolation is a common tenant-leakage bug. A user with membership in `acme` who visits `/orgs/evil-corp/dashboard` could see evil-corp's data if the app queries by the URL slug. Always derive the tenant ID from the session (`orgId`). #### Keeping the switcher in sync The `Sign in to continue.
returnWelcome back, {userId}
} ``` The `auth()` helper from `@clerk/nextjs/server` returns the signed-in user ID on both Server Components and Server Actions without requiring a client round-trip. Customization via the `appearance` prop plus CSS variables covers nearly every branding need without escaping the drop-in component model; teams that need full visual control still have full control through the theme system. Keyless mode (Core 3, March 3, 2026) accelerates local development by auto-provisioning a temporary sandbox instance without any manual key configuration — a development convenience, not a production deployment mode. Production uses standard Publishable Keys (`pk_live_*`) and Secret Keys (`sk_live_*`). ### First-Class Next.js, React, and Modern Framework Support Clerk integrates with Next.js 16 via native `proxy.ts` support (and supports `middleware.ts` for Next.js 15 and earlier). App Router patterns, Server Components, and Server Actions are all first-class citizens. The canonical Next.js 16 middleware setup: ```tsx import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server' const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/api/(.*)']) export default clerkMiddleware((auth, req) => { if (isProtectedRoute(req)) auth.protect() }) export const config = { matcher: ['/((?!_next|[^?]*\\.(?:html?|css|js|jpg|png|gif|svg)$).*)', '/(api|trpc)(.*)'], } ``` `createRouteMatcher` builds a URL predicate from one or more path patterns; `auth.protect()` redirects unauthenticated requests through the sign-in flow and makes the authenticated session available to the downstream route handler. The `matcher` config tells Next.js which request paths the proxy handles — excluding static assets by default so the auth layer only runs on application traffic. Recent additions to the Clerk framework story: [Expo](/glossary#expo) 3.1 native components (March 9, 2026), native iOS and Android SDKs at v1 (February 10, 2026), and the Core 3 SDK (March 3, 2026) which renamed `@clerk/clerk-react` to `@clerk/react` and `@clerk/clerk-expo` to `@clerk/expo` to align on the `@clerk/{details}
Edit src/routes/index.tsx to get started.
Signed-in-only content.
Sign in to see the dashboard.
{user?.emailAddresses[0]?.emailAddress}
{JSON.stringify(errors, null, 2)}
} ) } ``` Note the parameter rename: `redirectUrl` + `redirectUrlComplete` became `redirectCallbackUrl` + `redirectUrl`. **Callback page:** ```tsx 'use client' import { useClerk, useSignIn, useSignUp } from '@clerk/nextjs' import { useRouter } from 'next/navigation' import { useEffect, useRef } from 'react' export default function SSOCallback() { const clerk = useClerk() const { signIn } = useSignIn() const { signUp } = useSignUp() const router = useRouter() const hasRun = useRef(false) const handleNavigate = async ({ session, decorateUrl, }: { session: any decorateUrl: (url: string) => string }) => { if (session?.currentTask) { console.log(session?.currentTask) return } const url = decorateUrl('/') if (url.startsWith('http')) { window.location.href = url } else { router.push(url) } } useEffect(() => { ;(async () => { if (!clerk.loaded || hasRun.current) return hasRun.current = true // Happy path: sign-in completed by the OAuth provider if (signIn.status === 'complete') { await signIn.finalize({ navigate: handleNavigate }) return } // Transfer: OAuth returned a sign-up, but user has an existing account if (signUp.isTransferable) { await signIn.create({ transfer: true }) if (signIn.status === 'complete') { await signIn.finalize({ navigate: handleNavigate }) return } } // Additional transfer scenarios exist — see Clerk's OAuth custom flows docs // for handling signIn.isTransferable, existingSession, and other edge cases router.push('/sign-in') })() }, [clerk, signIn, signUp]) return (Loading...
return ({errors.fields.identifier.message}
} { errors?.fields?.password &&{errors.fields.password.message}
} ``` ### Handle needs\_client\_trust When [Client Trust](/docs/guides/secure/client-trust) is enabled and a user signs in from an unfamiliar device, `signIn.status` returns `needs_client_trust` instead of `complete`. Per the current Client Trust docs, this only applies to password-based authentication — passwordless methods (email links, OTPs, passkeys, OAuth) are unaffected. If the user has already enabled MFA, their existing MFA method takes precedence and the status will be `needs_second_factor` instead. Check the [Client Trust reference](/docs/guides/secure/client-trust) for the latest behavior details. Handle `needs_client_trust` by sending a verification code: ```tsx if (signIn.status === 'needs_client_trust') { // Find the email code factor const emailCodeFactor = signIn.supportedSecondFactors?.find( (factor) => factor.strategy === 'email_code', ) if (emailCodeFactor) { await signIn.mfa.sendEmailCode() // Show verification code input } } ``` After the user enters the code: ```tsx await signIn.mfa.verifyEmailCode({ code }) if (signIn.status === 'complete') { await signIn.finalize({ navigate: async ({ decorateUrl }) => { const url = decorateUrl('/dashboard') if (url.startsWith('http')) { window.location.href = url } else { router.push(url) } }, }) } ``` ### Always use decorateUrl Always wrap destination URLs with `decorateUrl` in the `navigate` callback. Clerk logs a development warning if it's not called when needed. Handle both return types: - **Absolute URL** (starts with `http`) — use `window.location.href` - **Relative path** — use your framework's client-side router ### Test in development first Clerk's development instances support the same custom-flow APIs as production. Test your migrated flows in a development instance before deploying to catch configuration issues early. ## Migration checklist 1. Run `npx @clerk/upgrade` (or pnpm/yarn/bun equivalent) 2. Verify `beforeEmit` to `navigate` renames applied by the CLI 3. Identify `setActive()` calls that finish auth flows (sign-in/sign-up completion) 4. Convert those calls to `signIn.finalize()` / `signUp.finalize()` 5. Keep `setActive()` for session switching and organization switching 6. Rewrite `navigate` callback bodies to use `{ session, decorateUrl }` 7. Add `needs_client_trust` status handling in sign-in flows 8. Configure `taskUrls` on `