Web Client Sessions

After a user signs in with Descope, your web app holds a session token and refresh token. The Client SDK stores them (typically in memory or a secure cookie) and refreshes the session token when it expires.

Your web app does not validate the session for API authorization — your backend does. The client's job is to:

Retrieve the session token from the SDK after authentication
Send it to your application server on each API request (usually as a Bearer token)
Manage logout and optional UI checks (expiry, roles for display)

See Session Validation for backend and gateway validation. See Sessions for the session and refresh token model.

If you're building APIs without a Descope backend SDK, you still need to validate every incoming token — see Backend validation.

Client SDK

Install SDK

Terminal

npm i --save @descope/react-sdk

Terminal

npm i --save @descope/nextjs-sdk

Terminal

npm i --save @descope/web-js-sdk

Terminal

npm i --save @descope/vue-sdk

Terminal

npm i --save @descope/angular-sdk

Import and initialize SDK

For more information about the baseUrl, baseStaticUrl, and baseCdnUrl parameters, refer to the Base URL Configuration section.

Parameters:

baseUrl: Custom domain that must be configured to manage token response in cookies. This makes sure every request to our service is through your custom domain, preventing accidental domain blockages.
baseStaticUrl: Custom domain to override the base URL that is used to fetch static files.
baseCdnUrl: Custom domain to override the base URL used to load external script assets (e.g., SDKs or widgets) dynamically at runtime.
persistTokens: Controls whether session tokens are stored in browser localStorage. Enabled by default and accessible via getToken(). Set to false to avoid client-side storage of tokens to reduce XSS risk.
autoRefresh: Controls whether the session is automatically refreshed when the token is expired. Enabled by default. Set to false to disable automatic refresh of the session.
sessionTokenViaCookie: Controls whether the session token is stored in a cookie instead of localStorage. If persistTokens is true, then by default, the token is stored in localStorage. Set this to true to store the token in a JS cookie instead.
storeLastAuthenticatedUser: Determines if the last authenticated user's info is saved in localStorage. Enabled by default and accessible via getUser(). Set to false to disable this behavior.
keepLastAuthenticatedUserAfterLogout: Controls whether user info is kept after logout. Disabled by default. Set to true to store user data on logout.

import { AuthProvider } from '@descope/react-sdk'
import { Descope, useDescope } from '@descope/react-sdk'

const AppRoot = () => {
	return (
      <AuthProvider
          projectId="__ProjectID__"
          baseUrl="https://auth.app.example.com"
          baseCdnUrl="https://assets.app.example.com" // specify a custom CDN URL for fetching external scripts and resources
          persistTokens={true} // set to `false` to disable token storage in browser to prevent XSS
          autoRefresh={true} // set to `false` to disable automatic refresh of the session
          sessionTokenViaCookie={false} // set to `true` to store the session token in a JS cookie instead of localStorage
          storeLastAuthenticatedUser={true} // set to `false` to disable storing last user
          keepLastAuthenticatedUserAfterLogout={false} // set to `true` to persist user info after logout
        >
        <App />
      </AuthProvider>
	);
};

import { AuthProvider } from '@descope/nextjs-sdk';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <AuthProvider
      projectId="__ProjectID__"
      baseUrl="<URL>"
      baseCdnUrl="https://assets.app.example.com" // specify a custom CDN URL for fetching external scripts and resources
      persistTokens={true} // set to `false` to disable token storage in browser to prevent XSS
      autoRefresh={true} // set to `false` to disable automatic refresh of the session
      sessionTokenViaCookie={false} // set to `true` to store the session token in a JS cookie instead of localStorage
      storeLastAuthenticatedUser={true} // set to `false` to disable storing last user
      keepLastAuthenticatedUserAfterLogout={false} // set to `true` to persist user info after logout
    >
      <html lang="en">
        <body>{children}</body>
      </html>
    </AuthProvider>
  );
}

import DescopeSdk from '@descope/web-js-sdk';
try {
  const descopeSdk = DescopeSdk({
    projectId: '__ProjectID__',
    baseUrl: 'https://auth.app.example.com',
    baseCdnUrl="https://assets.app.example.com", // specify a custom CDN URL for fetching external scripts and resources
    persistTokens: true, // set to `false` to disable token storage in browser to prevent XSS
    autoRefresh: true, // set to `false` to disable automatic refresh of the session
    sessionTokenViaCookie: false, // set to `true` to store the session token in a JS cookie instead of localStorage
    storeLastAuthenticatedUser: true, // set to `false` to disable storing last user
    keepLastAuthenticatedUserAfterLogout: false, // set to `true` to persist user info after logout
  });
} catch (error) {
  // handle the error
    console.log("failed to initialize: " + error)
}

import { createApp } from "vue";
import App from "@/App.vue";
import descope, { getSdk } from "@descope/vue-sdk";

const app = createApp(App);
app.use(router);

app.use(descope, {
  projectId: '__ProjectID__',
  baseUrl: "<base url>",
  baseCdnUrl: "https://assets.app.example.com", // specify a custom CDN URL for fetching external scripts and resources
  persistTokens: true, // set to `false` to disable token storage in browser to prevent XSS
  autoRefresh: true, // set to `false` to disable automatic refresh of the session
  sessionTokenViaCookie: false, // set to `true` to store the session token in a JS cookie instead of localStorage
  storeLastAuthenticatedUser: true, // set to `false` to disable storing last user
  keepLastAuthenticatedUserAfterLogout: false, // set to `true` to persist user info after logout
});

const sdk = getSdk();
sdk?.onSessionTokenChange((newSession) => {
  // here you can implement custom logic when the session is changing
});

// app.module.ts
import { NgModule, APP_INITIALIZER } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { DescopeAuthModule, DescopeAuthService, descopeInterceptor } from '@descope/angular-sdk';
import { AppComponent } from './app.component';
import {
  HttpClientModule,
  provideHttpClient,
  withInterceptors
} from '@angular/common/http';
import { zip } from 'rxjs';

export function initializeApp(authService: DescopeAuthService) {
  return () => zip([authService.refreshSession(), authService.refreshUser()]);
}

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    DescopeAuthModule.forRoot({
      projectId: 'YOUR_PROJECT_ID',
      baseUrl: '<URL>',
      baseCdnUrl: "https://assets.app.example.com", // specify a custom CDN URL for fetching external scripts and resources
      persistTokens: true, // set to `false` to disable token storage in browser to prevent XSS
      autoRefresh: true, // set to `false` to disable automatic refresh of the session
      sessionTokenViaCookie: false, // set to `true` to store the session token in a JS cookie instead of localStorage
      storeLastAuthenticatedUser: true, // set to `false` to disable storing last user
      keepLastAuthenticatedUserAfterLogout: false // set to `true` to persist user info after logout
    })
  ],
  providers: [
    {
      provide: APP_INITIALIZER,
      useFactory: initializeApp,
      deps: [DescopeAuthService],
      multi: true
    },
    provideHttpClient(withInterceptors([descopeInterceptor]))
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

OIDC Configuration

If you're using our SDK as an OIDC client with our Federated Apps, you can initialize the oidcConfig parameter with the following items:

applicationId: This is the application id, that can be found within the settings of your Federated Application
redirectUri: This is the url that will be redirected to if the user is unauthenticated. The default redirect URI will be used if not provided.
scope: This is a string of the scopes that the OIDC client will request from Descope. This should be one string value with spaces in between each scope. The default scopes are: 'openid email roles descope.custom_claims offline_access'

Sending session token to application server

If you are using Client SDK or using Descope Flows, then your application client must send the session token to you application server. The getSessionToken() function gets the sessionToken from local storage via JS which you can then include in your request.

Note

NextAuth does not use Descope's Client SDK but does use JWTs for session management.

import { getSessionToken } from '@descope/react-sdk';

const sessionToken = getSessionToken();

// example fetch call with authentication header
fetch('your_application_server_url', {
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer '+ sessionToken,
  }
})

// server components
import { getServerSession } from 'next-auth'
import { authOptions } from '@/app/_utils/options'

const session = await getServerSession(authOptions)

// client components
'use client'

import { useSession } from "next-auth/react"

const { data: session } = useSession()

import descopeSdk from '@descope/web-js-sdk';

const descopeSdk = descopeSdk({projectId: __ProjectID__});

const sessionToken = descopeSdk.getSessionToken();
// example fetch call with authentication header
fetch('your_application_server_url', {
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer '+ sessionToken,
  }
})

<script>
  const descopeSdk = Descope({projectId: "__ProjectID__"});

  const sessionToken = descopeSdk.getSessionToken();

  // example fetch call with authentication header
  fetch('your_application_server_url', {
    headers: {
      Accept: 'application/json',
      Authorization: 'Bearer '+ sessionToken,
    }
  })
</script>

import { DescopeAuthService } from '@descope/angular-sdk';

private authService = inject(DescopeAuthService);

token = getSessionToken()

At any time, your web client should send only the session token to your application server. Your server validates it with the Descope Backend SDK (or an API gateway JWT authorizer) before serving protected data.

Logout using Client SDK

If you are integrating using the Descope Client SDK, then you must use the Client SDK to logout. If you are using Descope Flows with React SDK, refer to the Quick Start for details. If you are Descope Client SDK without flows, then refer to the sample code below for logout.

Note

If you're using NextAuth and Next.js, you'll need to also make sure that you're handling the logout using the federated IdP revocation endpoint. You can see this working in a sample app here.

import DescopeSdk from '@descope/web-js-sdk';

const descopeSdk = Descope({projectId: "__ProjectID__"});

// Logout from the current session
const resp = await descopeSdk.logout();

// Logout from all the sessions
const resp = await descopeSdk.logoutAll();

// Sign out with NextAuth works a bit differently then you may be expecting. The reason is that, by using NextAuth, you're creating a NextAuth session between NextAuth and your client but also an OIDC session between Descope and NextAuth.
// Therefore, you'll need to make sure both sessions are cleared when logging out, which is detailed below.

---------------
// /app/signout/page.tsx

"use client";

import { useEffect } from "react";
import { useRouter } from "next/navigation";
import { signOut } from "next-auth/react";

function SignOutCallback() {
  const router = useRouter();

  useEffect(() => {
    const performSignOut = async () => {
      await signOut({ redirect: false });
      router.push("/");
    };

    performSignOut();
  }, [router]);

  return <div>Signing out...</div>;
}

---------------
// /app/api/auth/federated-sign-out

import { authOptions } from "@/app/_utils/options";
import { getServerSession } from "next-auth";
import { NextRequest, NextResponse } from "next/server";

export const dynamic = "force-dynamic";

const handler = async (req: NextRequest, res: NextResponse) => {
  try {
    const session = await getServerSession(authOptions);
    if (!session) {
      return NextResponse.redirect(process.env.NEXTAUTH_URL!);
    }

    const endSessionURL = `https://api.descope.com/oauth2/v1/logout`;
    const redirectURL = `${process.env.NEXTAUTH_URL}/signout`;
    const endSessionParams = new URLSearchParams({
      // @ts-ignore
      id_token_hint: session.idToken,
      post_logout_redirect_uri: redirectURL,
    });
    const fullUrl = `${endSessionURL}?${endSessionParams.toString()}`;
    return NextResponse.redirect(fullUrl);
  } catch (error) {
    console.error(error);
  }
};
export const GET = handler;

---------------
// app/components/signout-button

"use client";

import { signOut } from "next-auth/react";

function SignOutButton() {
  return (
      <button
        onClick={async () => {
          window.location.href = `/api/auth/federated-sign-out`;
        }}
      >
        Sign Out
      </button>
    </div>
  );
}

const descopeSdk = Descope({projectId: "__ProjectID__"});

// Logout from the current session
const resp = await descopeSdk.logout();

// Logout from all the sessions
const resp = await descopeSdk.logoutAll();

<script>
  const descopeSdk = Descope({projectId: "__ProjectID__"});

  // Logout from the current session
  const resp = await descopeSdk.logout();

  // Logout from all the sessions
  const resp = await descopeSdk.logoutAll();

</script>

import { Component, OnInit } from '@angular/core';
import { DescopeAuthService } from '@descope/angular-sdk';

@Component({
	selector: 'app-home',
	templateUrl: './app.component.html',
	styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {
	isAuthenticated: boolean = false;
	userName: string = '';

	constructor(private authService: DescopeAuthService) {}

	ngOnInit() {
		this.authService.session$.subscribe((session) => {
			this.isAuthenticated = session.isAuthenticated;
		});
		this.authService.user$.subscribe((descopeUser) => {
			if (descopeUser.user) {
				this.userName = descopeUser.user.name ?? '';
			}
		});
	}

	logout() {
		this.authService.descopeSdk.logout();
	}
}

Checking token expiration (UI only)

You can check whether the session token has expired before making API calls or updating UI state. This is a client-side convenience — it does not replace backend validation.

import { getSessionToken, useDescope } from '@descope/react-sdk'

const sessionToken = descopeSdk.getSessionToken();

const sdk = useDescope()

if(sdk.isJwtExpired(sessionToken)) {
  console.log('Session token has expired.');
} else {
  console.log('Session token is valid.');
}

'use client'

import { useSession } from "next-auth/react"

const { data: session } = useSession()

if((session)) {
  console.log('Session token has expired.');
} else {
  console.log('Session token is valid.');
}

const descopeSdk = descopeSdk({projectId: '__ProjectID__'});
const sessionToken = descopeSdk.getSessionToken();

if(isJwtExpired(sessionToken)) {
  console.log('Session token has expired.');
} else {
  console.log('Session token is valid.');
}

<script>
  const descopeSdk = Descope({projectId: "__ProjectID__"});
  const sessionToken = descopeSdk.getSessionToken();

  if(isJwtExpired(sessionToken)) {
    console.log('Session token has expired.');
  } else {
    console.log('Session token is valid.');
  }
</script>

Roles and permissions (UI only)

You can read roles and permissions from the session token to drive UI (show/hide menus, etc.). Do not rely on these values for authorization — your backend must validate the token and enforce access on every API request.

import { getSessionToken, getJwtRoles } from '@descope/react-sdk'

const sessionToken = descopeSdk.getSessionToken();
const roles = getJwtRoles(sessionToken);

console.log('User roles:', roles);

const descopeSdk = descopeSdk({projectId: '__ProjectID__'});

const sessionToken = descopeSdk.getSessionToken();
const roles = getJwtRoles(sessionToken);

console.log('User roles:', roles);

<script>
  const descopeSdk = Descope({projectId: "__ProjectID__"});

  const sessionToken = descopeSdk.getSessionToken();
  const roles = getJwtRoles(sessionToken);

  console.log('User roles:', roles);
</script>

import { DescopeAuthService } from '@descope/angular-sdk';

private authService = inject(DescopeAuthService);

this.authService.descopeSdk.getJwtRoles(token = getSessionToken(), tenant = '')

Permissions (UI only)

Permissions can also be read from the session token for display purposes using getJwtPermissions. Enforce permissions on your server, not in the browser.

import { getSessionToken, getJwtPermissions } from '@descope/react-sdk'

const sessionToken = descopeSdk.getSessionToken();
const permissions = getJwtPermissions(sessionToken);

console.log('User permissions:', permissions);

const descopeSdk = descopeSdk({projectId: '__ProjectID__'});

const sessionToken = descopeSdk.getSessionToken();
const permissions = getJwtPermissions(sessionToken);

console.log('User permissions:', permissions);

<script>
const descopeSdk = Descope({projectId: "__ProjectID__"});

const sessionToken = descopeSdk.getSessionToken();
const permissions = getJwtPermissions(sessionToken);

console.log('User permissions:', permissions);
</script>

import { DescopeAuthService } from '@descope/angular-sdk';

private authService = inject(DescopeAuthService);

getJwtPermissions(token = getSessionToken(), tenant = '')

Was this helpful?

On this page