Password Authentication with Client SDKs

This guide is meant for developers that are NOT using Descope Flows to design login screens and authentication methods.

If you'd like to use Descope Flows, Quick Start should be your starting point.

The Password-based 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

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

Client SDK

Install SDK

Terminal

npm i --save @descope/react-sdk

Import and initialize SDK

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>
	);
};

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.

// 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);
}

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.

// 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);
}

Update Password

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

// 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")
}

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.

// 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")
}

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.

// 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")
}

Get Password Policy

Get the configured password policy for the project.

// 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)
}

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.

Checkpoint

Your application is now integrated with Descope. Please test with sign-up or sign-in use case.

Need help?

Was this helpful?

Checkpoint

On this page