Password Authentication with Mobile SDKs

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

New user signup: User Sign-Up returns a jwt for the user.
Existing user signin: User Sign-In returns a jwt for the user.

Client SDK

Install SDK

// 1. Within XCode, go to File > Add Packages
// 2. Search for the URL of the git repo: https://github.com/descope/descope-swift
// 3. Configure your desired dependency rule
// 4. Click Add Package

// 1. Within Android Studio, go to File > Project Structure > Dependencies > Add Dependency > 1 Library Dependency
// 2. Search for the dependency: "com.descope"
// 3. Configure your desired dependency rules
// 4. Click "Ok"

// 1. From your Flutter project directory root, install the Descope SDK by running: flutter pub add descope
// 2. Or, add Descope to your pubspec.yml by including this line: descope: ^0.6.0
// View the package on pub.dev: https://pub.dev/packages/descope

// 1. From your React Native project directory root, install the Descope SDK by running: npm i @descope/react-native-sdk
// View the package: https://github.com/descope/descope-react-native

Import and initialize SDK

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.

import DescopeKit
import AuthenticationServices

do {
    Descope.setup(projectId: "__ProjectID__") { config in
      // Optional: Only set baseURL if using a custom domain with Descope and managing token response with cookies
      config.baseURL = "https://auth.app.example.com"
    }
    print("Successfully initialized Descope")
} catch {
    print("Failed to initialize Descope")
    print(error)
}

import android.app.Application
import com.descope.Descope

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        try {
            Descope.setup(this, projectId = "__ProjectID__") {
              // Optional: Only set baseURL if using a custom domain with Descope and managing token response with cookies
              baseUrl = "https://auth.app.example.com"
              // Enable the logger
              if (BuildConfig.DEBUG) {
                logger = DescopeLogger()
              }
            }
        } catch (e: Exception) {
            Log.e("ERROR", e.stackTraceToString())
        }
    }
}

import 'package:descope/descope.dart';

// Where your application state is being created
Descope.setup('<Your-Project-Id>', (config) {
  // Optional: Only set baseURL if using a custom domain with Descope and managing token response with cookies
  config.baseUrl = 'https://auth.app.example.com';
});
await Descope.sessionManager.loadSession();

import { AuthProvider } from '@descope/react-native-sdk'

const AppRoot = () => {
  return (
    <AuthProvider
      projectId="__ProjectID__"
      // Optional: Only set baseURL if using a custom domain with Descope and managing token response with cookies
      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.

// Creates a new user that can later sign in with a password.
//
// - Parameters:
//   - loginId: What identifies the user when logging in, typically
//     an email, phone, or any other unique identifier.
//   - details: Optional details about the user signing up.
//   - password: The user's password.
//
// - Returns: An AuthenticationResponse value upon successful authentication.let loginId = "email@company.com" //    user: Optional user object to populate new user information.
let details = SignUpDetails(name: "Joe Person", phone: "+15555555555", email: "email@company.com")
//    password (str): The user's password
let password = "xxxxxx"
do {
  let resp = try await Descope.password.signUp(loginId: loginId, password: password, details: details)
  print("Successfully signed up via password")
  completionHandler(true, nil)
} catch let descopeErr as DescopeError {
  print(descopeErr)
  completionHandler(false, descopeErr)
}

// - Parameters:
//   - loginId: What identifies the user when logging in, typically
//     an email, phone, or any other unique identifier.
//   - details: Optional details about the user signing up.
//   - password: The user's password.

val details = SignUpDetails(
    name = "firstName lastName",
    email = "email@company.com",
    phone = "+15555555555",
    givenName = "firstName",
    middleName = "middleName",
    familyName = "lastName"
)
try {
    Descope.password.signUp(loginId = "email@company.com", password = "xxxxxx", details = details)
} catch (e: Exception) {
    Log.e("ERROR", e.stackTraceToString())
}


// Creates a new user that can later sign in with a password.
//
// - Parameters:
//   - loginId: What identifies the user when logging in, typically
//     an email, phone, or any other unique identifier.
//   - details: Optional details about the user signing up.
//   - password: The user's password.
//
const loginId = "loginId";
const details = SignUpDetails(name: "Name");
const password = "password";
  Descope.password.signUp(loginId: loginId, password: password);

// 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.

// Authenticates an existing user using a password.
//
// - Parameters:
//   - loginId: What identifies the user when logging in,
//     typically an email, phone, or any other unique identifier.
//   - password: The user's password.
//
// - Returns: An ``AuthenticationResponse`` value upon successful authentication.
let loginId = "email@company.com" //    password (str): The user's password
let password = "xxxxxx"
do {
  let resp = try await Descope.password.signIn(loginId: loginId, password: password)
  completionHandler(true, nil)
} catch let descopeErr as DescopeError {
  print(descopeErr)
  completionHandler(false, descopeErr)
}

// - Parameters:
//   - loginId: What identifies the user when logging in,
//     typically an email, phone, or any other unique identifier.
//   - password: The user's password.
try {
    Descope.password.signIn(loginId = "email@company.com", password = "xxxxxx")
} catch (e: Exception) {
    Log.e("ERROR", e.stackTraceToString())
}

// Authenticates an existing user using a password.
//
// - Parameters:
//   - loginId: What identifies the user when logging in,
//     typically an email, phone, or any other unique identifier.
//   - password: The user's password.
//
// - Returns: An ``AuthenticationResponse`` value upon successful authentication.
const loginId = "loginId";
const details = SignUpDetails(name: "Name");
const password = "password";
  Descope.password.signIn(loginId: loginId, password: password);

// 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.

// In order to do this, the user must have an active ``DescopeSession`` whose
// `refreshJwt` should be passed as a parameter to this function.
//
// The value for `newPassword` must conform to the password policy defined in the
// password settings in the Descope console
//
// - Parameters:
//   - loginId: The existing user's loginId.
//   - newPassword: The new password to set for the user.
//   - refreshJwt: The existing user's `refreshJwt` from an active ``DescopeSession``.
let loginId = "email@company.com" //    password (str): The user's password
let newPassword = "xxxxxx"
let refreshJwt = "xxxxxxxxx"
do {
  let resp = try await Descope.password.update(loginId: loginId, newPassword: newPassword, refreshJwt: refreshJwt)
  completionHandler(true, nil)
} catch let descopeErr as DescopeError {
  print(descopeErr)
  completionHandler(false, descopeErr)
}

// - Parameters:
//   - loginId: The existing user's loginId.
//   - newPassword: The new password to set for the user.
//   - refreshJwt: The existing user's `refreshJwt` from an active ``DescopeSession``.
try {
    Descope.password.update(loginId = "email@company.com", newPassword = "xxx", refreshJwt = "xxx")
} catch (e: Exception) {
    Log.e("ERROR", e.stackTraceToString())
}

// In order to do this, the user must have an active ``DescopeSession`` whose
// `refreshJwt` should be passed as a parameter to this function.
//
// The value for `newPassword` must conform to the password policy defined in the
// password settings in the Descope console
//
// - Parameters:
//   - loginId: The existing user's loginId.
//   - newPassword: The new password to set for the user.
//   - refreshJwt: The existing user's `refreshJwt` from an active ``DescopeSession``.
const loginId = "email@company.com"; //    password (str): The user's password
const newPassword = "xxxxxx";
final refreshJwt = "xxxxxxxxx"
  Descope.password.update(
      loginId: loginId,
      newPassword: newPassword,
      refreshJwt: refreshJwt);

// 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.

/// Replaces a user's password by providing their current password.
///
/// The value for `newPassword` must conform to the password policy defined in the
/// password settings in the Descope console
///
/// - Parameters:
///   - loginId: The existing user's loginId.
///   - oldPassword: The user's current password.
///   - newPassword: The new password to set for the user.let loginId = "email@company.com" //    password (str): The user's password
let loginId = "<login_id>"
let newPassword = "xxxxxx"
let oldPassword = "xxxxxxxxx"
do {
  let resp = try await Descope.password.replace(loginId: loginId, oldPassword: oldPassword, newPassword: newPassword)
  completionHandler(true, nil)
} catch let descopeErr as DescopeError {
  print(descopeErr)
  completionHandler(false, descopeErr)
}

/// - Parameters:
///   - loginId: The existing user's loginId.
///   - oldPassword: The user's current password.
///   - newPassword: The new password to set for the user.let loginId = "email@company.com" //    password (str): The user's password

try {
    Descope.password.replace(loginId = "email@company.com", oldPassword = "xxx", newPassword = "xxx")
} catch (e: Exception) {
    Log.e("ERROR", e.stackTraceToString())
}

/// Replaces a user's password by providing their current password.
///
/// The value for `newPassword` must conform to the password policy defined in the
/// password settings in the Descope console
///
/// - Parameters:
///   - loginId: The existing user's loginId.
///   - oldPassword: The user's current password.
///   - newPassword: The new password to set for the user.let loginId = "email@company.com" //    password (str): The user's password
const loginId = "example@mail.com";
const oldPassword = "xxxxx";
const newPassword = "xxxxx";
  Descope.password.replace(loginId: loginId, oldPassword: password, newPassword: newPassword);

// 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.

// Sends a password reset email to the user.
//
// This operation starts a Magic Link or Enchanted Link flow depending on the
// configuration in the Descope console. After the authentication flow is finished
// use the `refreshJwt` to call `update` and change the user's password.
//
// - Important: The user must be verified according to the configured
// password reset method.
//
// - Parameters:
//   - loginId: The existing user's loginId.
//   - redirectURL: Optional URL that is used by Magic Link or Enchanted Link
//     if those are the chosen reset methods.let loginId = "email@company.com"
let loginId = "xxxxxxxxx"
do {
  let resp = try await Descope.password.sendReset(loginId: loginId, redirectURL: nil)
  completionHandler(true, nil)
} catch let descopeErr as DescopeError {
  print(descopeErr)
  completionHandler(false, descopeErr)
}


// - Parameters:
//   - loginId: The existing user's loginId.
//   - redirectURL: Optional URL that is used by Magic Link or Enchanted Link
//     if those are the chosen reset methods.let loginId = "email@company.com"
try {
    Descope.password.sendReset(loginId = "email@company.com", redirectUrl = "xxx")
} catch (e: Exception) {
    Log.e("ERROR", e.stackTraceToString())
}


// Sends a password reset email to the user.
//
// This operation starts a Magic Link or Enchanted Link flow depending on the
// configuration in the Descope console. After the authentication flow is finished
// use the `refreshJwt` to call `update` and change the user's password.
//
// - Important: The user must be verified according to the configured
// password reset method.
//
// - Parameters:
//   - loginId: The existing user's loginId.
//   - redirectURL: Optional URL that is used by Magic Link or Enchanted Link
//     if those are the chosen reset methods.let loginId = "email@company.com"
const loginId = "example@mail.com";
  Descope.password.sendReset(loginId: loginId);

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

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