Password Authentication

This authentication guide is meant for developers that are NOT using Descope to design login screens and authentication flows. If you’d like to use Descope Flows, Quick Start should be your starting point.

Introduction

The Passwords Authentication Method lets you authenticate end users using a secret string of characters known only to the user.

Descope recommends using an email address as the user identifier; this allows you to utilize passwordless methods like Magic Link in addition to passwords. These methods could be used for authentication when users forget their password or need to reset it easily.

Use Cases

  1. New user signup: The following actions must be completed, first User Sign-Up this returns a jwt for the user.
  2. Existing user signin: The following actions must be completed, first User Sign-In this returns a jwt for the user.

Install SDK

ReactNextJSNextAuthWebJSVue.jsHTMLAngular 
npm i --save @descope/react-sdk
npm i --save @descope/next-sdk
npm i --save next-auth
npm i --save @descope/web-js-sdk
npm i --save @descope/vue-sdk
<!-- Not applicable for HTML -->
npm i --save @descope/angular-sdk

Import and initialize SDK

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

const AppRoot = () => {
	return (
		<AuthProvider
			projectId="__ProjectID__"
			// If the Descope project manages the token response in cookies,
            // a custom domain must be configured
            // (e.g., https://auth.app.example.com)
			// and should be set as the baseUrl property.
			// baseUrl = "https://auth.app.example.com"
		>
			<App />
		</AuthProvider>
	);
};
import { AuthProvider } from '@descope/nextjs-sdk';

export default function RootLayout({ children }: { children: React.ReactNode }) {
	return (
		<AuthProvider projectId="__ProjectID__">
			<html lang="en">
				<body>{children}</body>
			</html>
		</AuthProvider>
	);
}
// app/api/auth/[...nextauth]
import { NextAuthOptions } from "next-auth"
import NextAuth from "next-auth/next";

export const authOptions: NextAuthOptions = {
  providers: [
    {
      id: "descope",
      name: "Descope",
      type: "oauth",
      wellKnown: `https://api.descope.com/${process.env.DESCOPE_PROJECT_ID}/.well-known/openid-configuration`,
      authorization: { params: { scope: "openid email profile" } },
      idToken: true,
      clientId: process.env.DESCOPE_PROJECT_ID,
      clientSecret: process.env.DESCOPE_ACCESS_KEY,
      checks: ["pkce", "state"],
      profile(profile) {
        return {
          id: profile.sub,
          name: profile.name,
          email: profile.email,
          image: profile.picture,
        }
      },
    },
  ], 
  callbacks: {
    async jwt({token, account, profile}) {
      if (account) {
        return {
          ...token,
          access_token: account.access_token,
          expires_at: Math.floor(Date.now() / 1000 + account.expires_in),
          refresh_token: account.refresh_token,
          profile: {
            name: profile?.name,
            email: profile?.email,
            image: profile?.picture,
            },
          }
        } else if (Date.now() < token.expires_at * 1000) {
          return token
        } else {
          try {
            const response = await fetch("https://api.descope.com/oauth2/v1/token", {
              headers: {"Content-Type": "application/x-www-form-urlencoded"},
              body: new URLSearchParams({
                client_id: "__ProjectID__",
                client_secret: "<Descope Access Key>",
                grant_type: "refresh_token",
                refresh_token: token.refresh_token,
              }),
              method: "POST",
            })
            
            const tokens = await response.json()
            
            if (!response.ok) throw tokens
            
            return {
              ...token,
              access_token: tokens.access_token,
              expires_at: Math.floor(Date.now() / 1000 + tokens.expires_in),
              refresh_token: tokens.refresh_token ?? token.refresh_token,
            }
          } catch (error) {
            console.error("Error refreshing access token", error)
            return {...token, error: "RefreshAccessTokenError"}
            }
          }
        },
    
        async session({session, token}) {
          if (token.profile) {
            session.user = token.profile;
          }
    
          session.error = token.error
          session.accessToken = token.access_token
          return session
        },
    }
}

const handler = NextAuth(authOptions)
export { handler as GET, handler as POST }

// app/provider.tsx
'use client'

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


export default function NextAuthSessionProvider(
    { children }:
    { children: React.ReactNode }
) {
    return (
        <SessionProvider>
            { children }
        </SessionProvider>
    )
}

// app/layout.tsx
import NextAuthSessionProvider from './provider'


export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <NextAuthSessionProvider>
          <div>
            {children}
          </div>
        </NextAuthSessionProvider>
      </body>
    </html>
  )
}
import DescopeSdk from '@descope/web-js-sdk';
try {
    //  baseUrl="<URL>" // you can also configure the baseUrl ex: https://auth.company.com - this is useful when you utilize CNAME within your Descope project.
    const descopeSdk = DescopeSdk({ projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });
} 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: '__Project_ID__',
  baseUrl: "<base url>", // Optional
});

const sdk = getSdk();
sdk?.onSessionTokenChange((newSession) => {
  // here you can implement custom logic when the session is changing
});
<head>
    <script src="https://unpkg.com/@descope/web-js-sdk@x.x.x/dist/index.umd.js"></script>
    <!-- Please replace `x.x.x` with the latest version of the WebJS SDK, which you can get from [here](https://www.npmjs.com/package/@descope/web-js-sdk) -->
</head>
// 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'
    })
  ],
  providers: [
    {
        provide: APP_INITIALIZER,
        useFactory: initializeApp,
        deps: [DescopeAuthService],
        multi: true
      },
      provideHttpClient(withInterceptors([descopeInterceptor]))
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

User Sign-Up

For registering a new user, your application client should accept user information, including an email or phone number used for verification. The application client should then send this information to your application server. Signing up via password returns the user's JWT.

ReactWebJSHTML 
// Args:
//    loginId (str): The login ID of the user being signed up
const loginId = "email@company.com"
//    password (str): The new user's password
const password = "xxxxxx"
//    user (dict) optional: Preserve additional user metadata in the form of
const user = { "name": "Joe Person", "phone": "+15555555555", "email": "email@company.com"}

const descopeSdk = useDescope();
const resp = await descopeSdk.password.signUp(loginId, password, user);
if (!resp.ok) {
  console.log("Failed to sign up via password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully signed up via password")
  console.log(resp);
}
// Args:
//    loginId (str): The login ID of the user being signed up
const loginId = "email@company.com"
//    password (str): The new user's password
const password = "xxxxxx"
//    user (dict) optional: Preserve additional user metadata in the form of
const user = { "name": "Joe Person", "phone": "+15555555555", "email": "email@company.com"}

const resp = await descopeSdk.password.signUp(loginId, password, user);
if (!resp.ok) {
  console.log("Failed to sign up via password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully signed up via password")
  console.log(resp);
}
<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function passwordSignUp() {
    // Args:
    //    user: Optional user object to populate new user information.
    const user = {
      "name": document.getElementById("name").value,
      "phone": document.getElementById("phone").value,
      "email": document.getElementById("email").value
    }
    //    password (str): The new user's password
    const password = document.getElementById("password").value
    //    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
    const loginId = document.getElementById("email").value

    const resp = await descopeSdk.password.signUp(loginId, password, user);
    if (!resp.ok) {
      window.alert("Failed to finish signup flow\nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully finished signup flow")
      window.location.replace("../loggedIn.html?userId=" + encodeURIComponent(loginId) + "&sessionJwt=" + resp.data.sessionJwt)
    }
  }
</script>

User Sign-In

For authenticating a user, your application client should accept the user's identity (typically an email address or phone number) and password. The application client should send this information to your application server. Signing in via password returns the user's JWT.

ReactWebJSHTML 
// Args:
//    loginId (str): The login ID of the user being signed in
const loginId = "email@company.com"
//    password (str): The user's password
const password = "xxxxxx"

const descopeSdk = useDescope();
const loginOptions = {
  customClaims: {
    claim1: "yes"
  }
}
const resp = await descopeSdk.password.signIn(loginId, password, loginOptions);
if (!resp.ok) {
  console.log("Failed to sign in via password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully signed in via password")
  console.log(resp);
}
// Args:
//    loginId (str): The login ID of the user being signed in
const loginId = "email@company.com"
//    password (str): The user's password
const password = "xxxxxx"
const loginOptions = {
  customClaims: {
    claim1: "yes"
  }
}
const resp = await descopeSdk.password.signIn(loginId, password, loginOptions);
if (!resp.ok) {
  console.log("Failed to sign in via password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully signed in via password")
  console.log(resp);
}
<script>
  let descopeSdk = Descope({projectId: "__ProjectID__", persistTokens: true, autoRefresh: true});

  async function passwordSignIn() {
    // Args:
    //    loginId: email or phone for the user
    const loginId = document.getElementById("loginId").value
    //    password (str): The new user's password
    const password = document.getElementById("password").value
    const loginOptions = {
      customClaims: {
        claim1: "yes"
      }
    }
    const resp = await descopeSdk.password.signIn(loginId, password, loginOptions);
    if (!resp.ok) {
      window.alert("Failed to finish signin flow\nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully finished signin flow")
      window.location.replace("../loggedIn.html?userId=" + encodeURIComponent(loginId) + "&sessionJwt=" + resp.data.sessionJwt)
    }
  }
</script>

Update Password

Update a password for an existing logged in user using their refresh token.

ReactWebJSHTML 
// Args:
//    loginId (str): The login ID of the user who's information is being updated
const loginId = "email@company.com"
//    newPassword (str): The new password to use
const newPassword = "xxxxxx"
//    token (str): The session's refresh token (used for verification)
const token = "xxxxxx"

const descopeSdk = useDescope();
const resp = await descopeSdk.password.update(loginId, newPassword, token);
if (!resp.ok) {
  console.log("Failed to update password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully updated password")
}
// Args:
//    loginId (str): The login ID of the user who's information is being updated
const loginId = "email@company.com"
//    newPassword (str): The new password to use
const newPassword = "xxxxxx"
//    token (str): The session's refresh token (used for verification)
const token = "xxxxxx"

const resp = await descopeSdk.password.update(loginId, newPassword, token);
if (!resp.ok) {
  console.log("Failed to update password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully updated password")
}
<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function updatePassword() {
    // Args:
    //    loginId (str): The login ID of the user who's information is being updated
    const loginId = document.getElementById("loginId").value
    //    newPassword (str): The new password to use
    const newPassword = document.getElementById("newPassword").value
    //    token (str): The session's refresh token (used for verification)
    const token = document.getElementById("refreshToken").value

    const resp = await descopeSdk.password.update(loginId, newPassword, token);
    if (!resp.ok) {
      window.alert("Failed to update password\nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully updated password")
      window.alert("Successfully updated password. After closing this alert, you will be directed to the login screen to login with your updated password")
      window.location.replace("./signInWithPassword")
    }
  }
</script>

Replace Password

Replace a password with a new one. The old password is used to authenticate the user before replacing the password. If the user cannot be authenticated, this operation will fail.

ReactWebJSHTML 
// Args:
//    loginId (str): The login ID of the user who's information is being replaced
const loginId = "email@company.com"
//    oldPassword (str): The user's current active password
const oldPassword = "xxxxxx"
//    newPassword (str): The new password to use
const newPassword = "xxxxxx"

const descopeSdk = useDescope();
const resp = await descopeSdk.password.replace(loginId, oldPassword, newPassword);
if (!resp.ok) {
  console.log("Failed to replace password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully replaced password")
}
// Args:
//    loginId (str): The login ID of the user who's information is being replaced
const loginId = "email@company.com"
//    oldPassword (str): The user's current active password
const oldPassword = "xxxxxx"
//    newPassword (str): The new password to use
const newPassword = "xxxxxx"

const resp = await descopeSdk.password.replace(loginId, oldPassword, newPassword);
if (!resp.ok) {
  console.log("Failed to replace password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully replaced password")
}
<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function replacePassword() {
    // Args:
    //    loginId (str): The login ID of the user who's information is being replaced
    const loginId = document.getElementById("loginId").value
    //    oldPassword (str): The user's current active password
    const oldPassword = document.getElementById("oldPassword").value
    //    newPassword (str): The new password to use
    const newPassword = document.getElementById("newPassword").value

    const resp = await descopeSdk.password.replace(loginId, oldPassword, newPassword);
    if (!resp.ok) {
      window.alert("Failed to replace password\nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully replaced password")
      window.alert("Successfully replaced password. After closing this alert, you will be directed to the login screen to login with your updated password.")
      window.location.replace("./signInWithPassword")
    }
  }
</script>

Reset Password

Sends a password reset prompt to the user with the given login id according to the password settings defined in the Descope console. NOTE: The user's email must be verified in order for the password reset method to complete.

ReactWebJSHTML 
// Args:
//    loginId (str): The login ID of the user who's password is being reset
const loginId = "email@company.com"
//    redirectURL (str): Optional parameter that is used by Magic Link.
const redirectURL = "http://auth.company.com/api/verify_magiclink"
//    templateOptions (TemplateOptions): Password reset email template options
const templateOptions = {"option": "Value1"}

const descopeSdk = useDescope();
const resp = await descopeSdk.password.sendReset(loginId, redirectURL, templateOptions);
if (!resp.ok) {
  console.log("Failed to send password reset")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully sent password reset")
}
// Args:
//    loginId (str): The login ID of the user who's password is being reset
const loginId = "email@company.com"
//    redirectURL (str): Optional parameter that is used by Magic Link.
const redirectURL = "http://auth.company.com/api/verify_magiclink"
//    templateOptions (TemplateOptions): Password reset email template options
const templateOptions = {"option": "Value1"}

const resp = await descopeSdk.password.sendReset(loginId, redirectURL, templateOptions);
if (!resp.ok) {
  console.log("Failed to send password reset")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully sent password reset")
}
<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function updatePassword() {
    // Args:
    //    loginId (str): The login ID of the user who's information is being updated
    const loginId = userId
    //    newPassword (str): The new password to use
    const newPassword = document.getElementById("newPassword").value
    //    token (str): The session's refresh token (used for verification)
    const token = refreshToken
    //    templateOptions (TemplateOptions): Password reset email template options
    const templateOptions = {"option": "Value1"}

    const resp = await descopeSdk.password.sendReset(loginId, redirectURL, templateOptions);
    if (!resp.ok) {
      window.alert("Failed to send password reset\nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully sent password reset")
      window.location.replace("./signInWithPassword")
    }
  }
</script>

Get Password Policy

Get the configured password policy for the project.

ReactWebJSHTML 
// Args:
//     None

const descopeSdk = useDescope();
const resp = await descopeSdk.password.policy();
if (!resp.ok) {
  console.log("Successfully returned password policy")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully sent password reset")
  console.log(resp)
}
// Args:
//     None

const resp = await descopeSdk.password.policy();
if (!resp.ok) {
  console.log("Successfully returned password policy")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully sent password reset")
  console.log(resp)
}
<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  getPasswordPolicy()

  async function getPasswordPolicy() {
    const resp = await descopeSdk.password.policy();
    if (!resp.ok) {
      window.alert("Failed to receive the project's password policy\nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully received the project's password policy")
      console.log(resp.data)
      window.alert("This is your password policy:\n\n" + JSON.stringify(resp.data, null, 2))
    }
  }
</script>

Session Validation

The final step of completing the authentication with Descope is to validate the user session. Descope provides rich session management capabilities, including configurable session timeouts and logout functions. You can find the details and sample code for client session validation here.



left parenthesis
Checkpoint: Your application is now integrated with Descope. Please test with sign-up or sign-in use case.
right parenthesis