Documentation Index
Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Use case
- Gate your app’s UI or navigation: Restrict access to application features that require authentication.
- Route authenticated users: Direct users with active sessions to your main application experience.
- Redirect unauthenticated users: Send users without sessions to your login or signup flow.
Retrieve a user session
Select a framework:
Follow our
Next.js quickstart for an example routing a user based on whether there’s an active session.
Determine where to authenticate sessions in your application
We recommend placing this logic close to the entry point to each page you want to control in your application.
Implement useStytchSession()
You can use the useStytchSession() hook to retrieve a user’s session data and listen for changes:import { useStytchSession } from '@stytch/nextjs';
import { useRouter } from 'next/navigation';
// Protected page example that routes a user to login if there's no active session
export default function Home() {
const { session, isInitialized } = useStytchSession();
const router = useRouter();
useEffect(() => {
// Route the user to login if there's no session
if (!session && isInitialized) {
router.replace("/login");
}
}, [session, isInitialized, router]);
if (!isInitialized || !session) {
// Show loading while redirecting or if the SDK hasn't finished initializing
return <p>Loading...</p>;
}
// If there's an active session, show the home content
return <p>Welcome! You have an active session.</p>;
}
Using the isInitialized and session values
The useStytchSession() hook returns the values:The active User Session object. null if there’s no active session. Whether or not the SDK has finished initializing. Ensure this is true before checking for an active session.
Whether the SDK is returning cached session data based on if the SDK has completed an Authenticate Session call or not. For most cases, you can rely on checking the session value as long as isInitialized is true.
Using cached data and fromCache
The frontend SDK utilizes stale-while-revalidate (SWR) for faster time-to-interactivity and UX:
- The page first loads.
- Stytch’s SDK checks and returns cached User and Session data to your application.
- The SDK refreshes User and Session data in background session authentication while your application starts.
For use cases where you’d prefer to wait until the session data finishes updating instead of relying on cached data, you can verify that fromCache is false before checking the session value. Follow our
React quickstart for an example routing a user based on whether there’s an active session.
Determine where to authenticate sessions in your application
We recommend placing this logic close to the entry point to each page you want to control in your application.
Implement useStytchSession()
You can use the useStytchSession() hook to retrieve a user’s session data and listen for changes:import { useStytchSession } from '@stytch/react';
import { Navigate } from "react-router";
// Protected page example that routes a user to login if there's no active session
export const Home = () => {
const { session } = useStytchSession();
// Route users to login if there's no active session
if (!session) {
return <Navigate to="/login" />;
}
return <p>Welcome! You have an active session.</p>;
};
Using the session value
The useStytchSession() hook returns the values:The active User Session object. null if there’s no active session. Whether the SDK has completed initialization.
Whether the SDK is returning cached session data based on if the SDK has completed an Authenticate Session call or not. For most cases, you can rely on checking the session value.
Using cached data and fromCache
The frontend SDK utilizes stale-while-revalidate (SWR) for faster time-to-interactivity and UX:
- The page first loads.
- Stytch’s SDK checks and returns cached User and Session data to your application.
- The SDK refreshes User and Session data in background session authentication while your application starts.
For use cases where you’d prefer to wait until the session data finishes updating instead of relying on cached data, you can verify that fromCache is false before checking the session value. Follow our
Vanilla JS quickstart for an example routing a user based on whether there’s an active session.
Determine where to authenticate sessions in your application
We recommend placing this logic close to the entry point to each page you want to control in your application.
Implement getSync() to retrieve session data
You can use the session.getSync() method to retrieve a user’s session data:import { stytch } from "./stytch-client.js"; // or where Stytch is initialized
function init() {
const session = stytch.session.getSync();
if (!session) {
// Redirect to login if there's no active session
window.location.href = "/login";
return;
}
// If there's an active session, show the protected content
document.getElementById('app').innerHTML = '<p>Welcome! You have an active session.</p>';
}
// Initialize when the page loads
document.addEventListener("DOMContentLoaded", init);
session.getSync() method returns the value:The active User Session object. null if there’s no active session. Implement onChange() to listen for changes
You can use the session.onChange() method to listen for changes in the user’s session:// Listen for session changes
const unsubscribeSession = stytch.session.onChange((newSession) => {
session = newSession;
// Trigger any relevant actions in your application based on the session update
handleSessionChange();
});
window.addEventListener('beforeunload', () => {
unsubscribeSession && unsubscribeSession();
});
- The method takes in a callback that gets called whenever the Session object changes.
- It returns an unsubscribe method for you to call when you no longer want to listen for changes.
