@descope/nextjs-sdk
Advanced tools
The Descope SDK for NextJS provides convenient access to the Descope for an application written on top of NextJS. You can read more on the Descope Website.
This SDK uses under the hood the Descope React SDK and Descope Node SDK Refer to the Descope React SDK and Descope Node SDK for more details.
Project ID is required for using the SDK. Find it on the project page in the Descope Console.Install the package with:
npm i --save @descope/nextjs-sdk
This section contains guides for App router and Pages router. For Pages router, see the Pages Router section.
// src/app/layout.tsx
import { AuthProvider } from '@descope/nextjs-sdk';
export default function RootLayout({
children
}: {
children: React.ReactNode
}) {
return (
<AuthProvider projectId="your-descope-project-id">
<html lang="en">
<body>{children}</body>
</html>
</AuthProvider>
);
}
Note: AuthProvider uses sessionTokenViaCookie by default, in order that the AuthMiddleware will work out of the box.
You can use default flows or provide flow id directly to the Descope component
// Login page, e.g. src/app/sign-in.tsx
import { Descope } from '@descope/nextjs-sdk';
// you can choose flow to run from the following without `flowId` instead
// import { SignInFlow, SignUpFlow, SignUpOrInFlow } from '@descope/nextjs-sdk'
const Page = () => {
return (
<Descope
flowId="sign-up-or-in"
onSuccess={(e) => console.log('Logged in!')}
onError={(e) => console.log('Could not logged in!')}
redirectAfterSuccess="/"
// redirectAfterError="/error-page"
/>
);
};
Refer to the Descope React SDK Section for a list of available props.
Note: Descope is a client component. if the component that renders it is a server component, you cannot pass onSuccess/onError/errorTransformer/logger props because they are not serializable. To redirect the user after the flow is completed, use the redirectAfterSuccess and redirectAfterError props.
Use the useDescope, useSession and useUser hooks in your components in order to get authentication state, user details and utilities
This can be helpful to implement application-specific logic. Examples:
Note: these hooks should be used in a client component only (For example, component with use client notation).
'use client';
import { useDescope, useSession, useUser } from '@descope/nextjs-sdk/client';
import { useCallback } from 'react';
const App = () => {
// NOTE - `useDescope`, `useSession`, `useUser` should be used inside `AuthProvider` context,
// and will throw an exception if this requirement is not met
// useSession retrieves authentication state, session loading status, and session token
const { isAuthenticated, isSessionLoading, sessionToken } = useSession();
// useUser retrieves the logged in user information
const { user } = useUser();
// useDescope retrieves Descope SDK for further operations related to authentication
// such as logout
const sdk = useDescope();
if (isSessionLoading || isUserLoading) {
return <p>Loading...</p>;
}
const handleLogout = useCallback(() => {
sdk.logout();
}, [sdk]);
if (isAuthenticated) {
return (
<>
<p>Hello {user.name}</p>
<button onClick={handleLogout}>Logout</button>
</>
);
}
return <p>You are not logged in</p>;
};
You can use NextJS Middleware to require authentication for a page/route or a group of pages/routes.
Descope SDK provides a middleware function that can be used to require authentication for a page/route or a group of pages/routes.
// src/middleware.ts
import { authMiddleware } from '@descope/nextjs-sdk/server'
export default authMiddleware({
// The Descope project ID to use for authentication
// Defaults to process.env.DESCOPE_PROJECT_ID
projectId: 'your-descope-project-id',
// The URL to redirect to if the user is not authenticated
// Defaults to process.env.SIGN_IN_ROUTE or '/sign-in' if not provided
// NOTE: In case it contains query parameters that exist in the original URL, they will override the original query parameters. e.g. if the original URL is /page?param1=1¶m2=2 and the redirect URL is /sign-in?param1=3, the final redirect URL will be /sign-in?param1=3¶m2=2
redirectUrl?: string,
// These are the public and private routes in your app. Read more about how to use these below.
publicRoutes?: string[],
privateRoutes?: string[]
// If you having privateRoutes and publicRoutes defined at the same time, privateRoutes will be ignored.
})
export const config = {
matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)']
}
publicRoutes: Use this to specify which routes do not require authentication. If specified, only these routes and the default public routes will be public.privateRoutes: Use this to specify which routes require authentication. If specified, only these routes will be private, and all other routes will be public.publicRoutes and privateRoutes are provided, privateRoutes will be ignored, and a warning will be logged.This setup ensures that you can clearly define which routes in your application require authentication and which do not, while providing a mechanism to handle potential misconfigurations gracefully.
publicRoutes to specify routes that don't require authentication.process.env.SIGN_IN_ROUTE or /sign-in if not providedprocess.env.SIGN_UP_ROUTE or /sign-up if not providedconst options = {
publicRoutes: ['/home', '/about']
};
privateRoutes to specify routes that require authentication. All other routes will be considered public.publicRoutes and privateRoutes are defined at the same time, privateRoutes will be ignored, and a warning will be logged.const options = {
privateRoutes: ['/dashboard', '/profile']
};
use the session() helper to read session information in Server Components and Route handlers.
Note: session() requires the authMiddleware to be used for the Server Component or Route handler that uses it.
Server Component:
// src/app/page.tsx
import { session } from '@descope/nextjs-sdk/server';
async function Page() {
const sessionRes = session();
if (!sessionRes) {
// ...
}
// Use the session jwt or parsed token
const { jwt, token } = sessionRes;
}
Route handler:
// src/pages/api/routes.ts
export async function GET() {
const currSession = session();
if (!currSession.isAuthenticated) {
// ...
}
// Use the session jwt or parsed token
const { jwt, token } = currSession;
}
Use createSdk function to create Descope SDK in server side.
Refer to the Descope Node SDK for a list of available functions.
Usage example in Route handler:
// src/pages/api/routes.ts
import { createSdk } from '@descope/nextjs-sdk/server';
const sdk = createSdk({
// The Descope project ID to use for authentication
// Defaults to process.env.DESCOPE_PROJECT_ID
projectId: 'your-descope-project-id',
// The Descope management key to use for management operations
// Defaults to process.env.DESCOPE_MANAGEMENT_KEY
managementKey: 'your-descope-management-key'
// Optional: Descope API base URL
// Defaults to process.env.DESCOPE_BASE_URL
// baseUrl: 'https://...'
});
export async function GET(req) {
const { searchParams } = new URL(req.url);
const loginId = searchParams.get('loginId');
const { ok, data: user } = await sdk.management.user.load(loginId);
if (!ok) {
// ...
}
// Use the user data ...
}
This section is Working in progress :-) In the meantime, you can see the example in the Pages Router folder.
Widgets are components that allow you to expose management features for tenant-based implementation. In certain scenarios, your customers may require the capability to perform managerial actions independently, alleviating the necessity to contact you. Widgets serve as a feature enabling you to delegate these capabilities to your customers in a modular manner.
Important Note:
Tenant Admin Role.The UserManagement widget will let you embed a user table in your site to view and take action.
The widget lets you:
Note:
import { UserManagement } from '@descope/nextjs-sdk';
...
<UserManagement
widgetId="user-management-widget"
tenant="tenant-id"
/>
Example: Manage Users
The RoleManagement widget will let you embed a role table in your site to view and take action.
The widget lets you:
Note:
Editable field is determined by the user's access to the role - meaning that project-level roles are not editable by tenant level users.import { RoleManagement } from '@descope/nextjs-sdk';
...
<RoleManagement
widgetId="role-management-widget"
tenant="tenant-id"
/>
Example: Manage Roles
The AccessKeyManagement widget will let you embed an access key table in your site to view and take action.
The widget lets you:
import { AccessKeyManagement } from '@descope/nextjs-sdk';
{
/* admin view: manage all tenant users' access keys */
}
<AccessKeyManagement
widgetId="access-key-management-widget"
tenant="tenant-id"
/>;
{
/* user view: mange access key for the logged-in tenant's user */
}
<AccessKeyManagement
widgetId="user-access-key-management-widget"
tenant="tenant-id"
/>;
Example: Manage Access Keys
The AuditManagement widget will let you embed an audit table in your site.
import { AuditManagement } from '@descope/nextjs-sdk';
...
<AuditManagement
widgetId="audit-management-widget"
tenant="tenant-id"
/>
Example: Manage Audit
The UserProfile widget lets you embed a user profile component in your app and let the logged in user update his profile.
The widget lets you:
import { UserProfile } from '@descope/nextjs-sdk';
...
<UserProfile
widgetId="user-profile-widget"
onLogout={() => {
// add here you own logout callback
window.location.href = '/login';
}}
/>
Example: User Profile
The ApplicationsPortal lets you embed an applications portal component in your app and allows the logged-in user to open applications they are assigned to.
import { ApplicationsPortal } from '@descope/nextjs-sdk';
...
<ApplicationsPortal
widgetId="applications-portal-widget"
/>
Example: User Profile
You can find an example react app in the examples folder. - App Router - Pages Router
To learn more please see the Descope Documentation and API reference page.
If you need help you can email Descope Support
The Descope SDK for React is licensed for use under the terms and conditions of the MIT license Agreement.
FAQs
Descope NextJS SDK
The npm package @descope/nextjs-sdk receives a total of 4,808 weekly downloads. As such, @descope/nextjs-sdk popularity was classified as popular.
We found that @descope/nextjs-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."