Login (iOS SDK)

Our SDK provides a set of components for secure-input of authentication credentials for various scenarios. This section covers our two login components:

Password - For password-based authentication.
OTP (One-Time Password) - For verification of user via an OTP.

Each component is designed with security features, including built-in text masking, secure handling, and proper validation.

The components allow a user to input their credentials in a secure fashion, which is converted into a user session token. This can then be used to execute requests with our API, allowing the user to interact with their financial instruments and our services.

There are two ways to submit a password to POST /login_with_password, and the approach you choose determines whether you use our secure components.

Capture the password with our secure login component and convert it into a one-time-use token. The password is encrypted inside a view your app cannot read, so your code and servers never see the plaintext. You exchange the token - not the password - for a session.

Use this approach for the standard Weavr security model. Because the plaintext never touches your app, you stay out of PCI DSS scope and qualify for the lightest Self-Assessment Questionnaire. This is the approach the rest of this page documents.

If you don't use our tokenisation for the password - for example, you already operate a PCI DSS-compliant environment that handles the plaintext securely - capture the password in your own native field, validate it there, then submit the plaintext value to POST /login_with_password from your server.

Accepting a plaintext password at POST /login_with_password requires configuration by our team and isn't something you can turn on yourself in the Weavr portal. Reach out to our support team to enable it before you build this flow.

In this case, don't use our secure login component. The component exists to tokenise the value inside a sandboxed view; it deliberately gives your code no way to read or validate the plaintext a user types, so it can't back a flow that needs the raw password.

Prefer tokenised login

Tokenised login is preferred for every integration that doesn't already carry its own PCI DSS obligations, because it keeps the plaintext password out of your systems entirely.

Our login components each render one credential field inside a tokenised view. The mockup below shows where they typically appear in your app - hover the numbered hotspots for the underlying class names.

your app

Sign in

Welcome back

Password

••••••••

One-time code

Hover or focus a numbered hotspot to see which secure component renders each field - click to jump to its docs.

Features

All components share these security features:

Secure text masking
Input type enforcement
Length validation
Secure text handling
Tokenization support
Error handling
UI customization options

Password - `SecurePasswordField`

Use it for: login screens, sign-up password creation, and change-password flows.

Use this component for password-based authentication (something you know). It ensures secure text input with masking and validation.

Password complexity

Customer passwords must satisfy all of the following:

8 to 30 characters
at least one uppercase letter
at least one lowercase letter
at least one number
at least one special character
different from the user's last 5 passwords

Validate password

Surface these rules in your sign-up and change-password screens before the user submits.

To check a candidate password against the same rules without committing it, call POST /passwords/validate from your server. The endpoint returns success if the password meets the policy and a conflict response if it doesn't.

Submit password

The API rejects passwords that don't meet these requirements with AUTH_009 PASSWORD_POLICY_VIOLATION.

Security features

Secure text masking
Input type enforcement
Maximum length validation (100 characters)
Secure text handling

Integration

In code
Storyboard

lazy var securePasswordField: SecurePasswordField = {
    let textField = SecurePasswordField()
    textField.placeholder = "Password"
    textField.frame = CGRect(x: 10, y: 100, width: 300, height: 30)
    return textField
}()

This can be achieved by dragging and dropping the UITextField component to your storyboard. After that, go to the component's Identity inspector and type SecurePasswordField in the Class block, and WeavrComponents in the Module block.

At this point, If you hit ctrl + R or click run at Xcode, you can see the password mobile component in your device/Simulator.

OTP - `SecureSmsOtpFields`

Use it for: SMS one-time-password screens, typically for step-up authentication or phone-number verification during sign-up.

For One-Time Passwords (6 digits, segmented).

In code
Storyboard

lazy var SecureSmsOtpFields: SecureSmsOtpFields = {
    let textField = SecureSmsOtpFields()
    textField.placeholder = "One-Time Password"
    textField.frame = CGRect(x: 10, y: 100, width: 300, height: 30)
    return textField
}()

This can be achieved by drag and dropping the UITextField component to your storyboard. After that go to the component's Identity inspector and type SecureSmsOtpFields in the Class block, and WeavrComponents in the Module block.

At this point, If you hit ctrl + R or click run at Xcode, you can see the password mobile component in your device/Simulator.

Token management workflow

The login components are used to create a tokenised representation of the user input, allowing you to send sensitive information to our servers without interacting directly with it.

Tokenization reduces PCI scope

By transmitting and receiving PCI-sensitive data in tokenized form, you qualify for the lowest level of PCI compliance.

Creating tokens

class MyViewController: UIViewController {
    @IBOutlet weak var mySecurePasscode: SecurePasscodeField!

    func tokenizePassword() {
        mySecurePasscode.createToken { result in
            switch result {
            case .failure(let error):
                print("Something went wrong \(error)")
            case .success(let tokens):
                print("Token: \(tokens.first?.value ?? "No token")")
            }
        }
    }
}

Additionally, you can avoid multiple round-trips to our servers by grouping multiple tokenization requests into one.

You can read more on group tokenization here.

Setting a user token

After a successful login, you should set the user access token within the SDK via:

UXComponents.setUserToken(token: token) { result in
    switch result {
    case .failure(let e):
        print("Something went wrong: \(e)")
    case .success(let result):
        print("User token associated: \(result)")
    }
}

Verifying token association

At any point in time, you can validate if a token is available by checking if there's an associated user:

let isAssociated = UXComponents.isAssociated()

Resetting user association

When the user logs out of your application, you can reset the association with:

UXComponents.resetAssociation()

Listeners

Both SecurePasswordField and SecureSmsOtpFields support setting a TextEntryCompleteDelegate that notifies you if the user enters an input matching the maximum length of the password.

When the user enters a password, you'll likely want to let the user tap on the login button before logging them in.

The next snippet showcases how to use TextEntryCompleteDelegate.

class MyViewController: UIViewController {
    @IBOutlet weak var mySecurePassword: SecurePasswordField!

    override func viewDidLoad() {
        super.viewDidLoad()
        mySecurePassword.textEntryCompleteDelegate = self
    }
}

extension MyViewController: TextEntryCompleteDelegate {
    func onTextEntryComplete(_ textField: SecureTextField) {
        print("Password completed!")
    }
}

Security tips

Always use secure input types (isSecureTextEntry = true)
Implement proper error handling
Use appropriate token management
Validate input length and format

Passcodes

We support passcodes via our Android SDK, but Apple does not allow this on iOS. See Apple's Human Interface Guidelines on managing accounts.

Frequently asked questions

What happens if a user has already enrolled their device for Biometric Authentication, but then re-installs the app?
In this case, the user needs to re-enroll the device for biometrics. This also applies if the user clears cache or data of the app.
If the configuration of the passcode length changes, what is the impact on existing users?
If the program was configured with a passcode length of 4 digits, and this is changed to 6, the user continues to be able to log in with their existing passcode of 4 digits. However, when they change their passcode (via the "forgot passcode" flow) they are required to choose a passcode with the new length (6 in this example).
How does the forgot passcode flow work?
The forgotten passcode flow is initiated from the Weavr API. If an email has been set for the active user, an email is sent containing a URL that redirects the user to change their passcode.
Does the user have multiple attempts at login and challenges via Biometrics Authentication?
For situations when biometrics fail (wrong fingerprint, not enough light, etc.) the user can retry multiple times. If biometrics continues to fail after too many attempts, it automatically triggers the passcode log-in, which also allows multiple attempts.
How many retries are available until the user is blocked?
The default value is 3. After 3 failed biometric attempts, the user is presented with the passcode fallback screen, where 3 attempts are also allowed. The passcode is our Authentication passcode that the user chose when they were created as a user on Weavr, not the one that unlocks their device.
When is the user blocked if biometrics and passcode fail and for how long?
After 3 biometric attempts and 3 wrong passcode attempts, the user gets blocked for 30 minutes.

Choosing a login approach​

Tokenised login (preferred)​

Non-tokenised login​

Where each component fits in your login screen​

Sign in

Features​

Password - SecurePasswordField​

Password complexity​

Validate password​

Submit password​

Security features​

Integration​

OTP - SecureSmsOtpFields​

Token management workflow​

Creating tokens​

Setting a user token​

Verifying token association​

Resetting user association​

Listeners​

Security tips​

Frequently asked questions​

Choosing a login approach

Tokenised login (preferred)

Non-tokenised login

Where each component fits in your login screen