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/swift-sdk
// 3. Configure your desired dependency rule
// 4. Click Add Package

Import and initialize SDK

import DescopeKit
import AuthenticationServices
 
do {
    Descope.setup(projectId: "__ProjectID__")
    print("Successfully initialized Descope")
} catch {
    print("Failed to initialize Descope")
    print(error)
}

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

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

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

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

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

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