Login (React Native SDK)

Our SDK provides components for secure-input of authentication credentials. Each component captures one credential field inside a tokenised view, returning a one-time use token you exchange for a user session.

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.

The mockup below shows where each component typically appears in your app - hover the numbered hotspots for the underlying class names.

your app

Sign in

Welcome back

Password

••••••••

Passcode

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

Password - `SecurePasswordTextField`

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

The mobile Password component collects the user's password, which can be used as one factor (something you know) when accessing financial services.

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.

Using the component

Once you have installed and initialized our React Native SDK, you can integrate the mobile Password component. Import the component directly using the code below:

import { SecurePasswordTextField } from "@weavr-io/secure-components-react-native";
const textFieldRef = useRef<any>();
//tag is only required for group actions
const [tagPass1, setTagPass1] = React.useState<string | undefined>();
<SecurePasswordTextField
  placeholder="Enter Password"
  style={styles.fieldBox} //only define sizing
  fontStyle={{
    fontFamily: "Lobster-Regular",
    fontSize: 16,
    color: "#8080cc",
  }}
  background={true} //here default behaviour is system default
  onCreateToken={onPassToken}
  onGetTag={(resp: any) => {
    console.log(resp);
    setTagPass1(resp.value);
  }}
  onTextChanges={(resp) => {
    console.log(resp);
  }}
  onFocus={(resp) => {
    console.log(resp);
  }}
  onBlur={(resp) => {
    console.log(resp);
  }}
  ref={textFieldRef}
  placeholderTextColor="#000000"
/>;

Create a token from the Text Field component:

textFieldRef.current.createToken();
//it receives the tokenized password
const onPassToken = (resp: any) => {
  console.log(resp);
  setPassword(resp.value);
  Toast.show(resp.value);
};

Set the user token in the SDK

import { setUserToken } from "@weavr-io/secure-components-react-native";
setUserToken(token).then((res: any) => {
  console.log(res);
});

Check if an association exists with the SDK

import { isAssociated } from "@weavr-io/secure-components-react-native";

isAssociated().then((res) => {
  if (res) {
    //do your stuff
  } else {
    console.log("You must login first to continue!");
  }
});

Passcode - `SecurePasscodeTextField`

Passcode is Android-only - do not use on iOS

Apple does not permit numeric passcodes as an authentication method, so the passcode component is not supported on iOS. If your app targets iOS (including cross-platform React Native apps), use the Password component for iOS users.

Use passcode only on Android, or gate the component with Platform.OS === 'android'. On iOS, password is the biometric fallback.

Use it for: Android login screens that authenticate the user with a 4-digit passcode, and as the fallback input when biometric authentication fails. On iOS, use the Password component instead.

The mobile Passcode component collects the user's passcode on Android only, where it can be used as one factor (something you know) when accessing financial services. On Android, when you use Biometric Authentication, the passcode is the fallback input method if biometry fails (for example, a fingerprint is not recognized). On iOS, the password component fills this role instead.

Once you have installed and initialized our React Native SDK, you can integrate the mobile Passcode Component on Android. Import the component directly using the code below:

import { SecurePasscodeTextField } from "@weavr-io/secure-components-react-native";
const textFieldRef = useRef<any>();
//tag is only required for group actions
const [tagPass1, setTagPass1] = React.useState<string | undefined>();
<SecurePasscodeTextField
  placeholder="Enter Passcode"
  style={styles.fieldBox} //only define sizing
  fontStyle={{
    fontFamily: "Lobster-Regular",
    fontSize: 16,
    color: "#8080cc",
  }}
  background={true} //here default behaviour is system default
  onCreateToken={onPassToken}
  onGetTag={(resp: any) => {
    console.log(resp);
    setTagPass1(resp.value);
  }}
  onTextChanges={(resp) => {
    console.log(resp);
  }}
  onBlur={(resp) => {
    console.log(resp);
  }}
  onFocus={(resp) => {
    console.log(resp);
  }}
  ref={textFieldRef}
  placeholderTextColor="#000000"
  onTextEntryComplete={() => {
    dLog("Text Entry completed");
  }}
  isSegmented={true} //mandatory if you want to use segmented fields
  //following props are for segmented passcode only
  placeholderTextColor="#808080"
  fieldBackgroundColor="#ffffff" //ios Only
  enableBorder={true}
  borderRadius={15}
  borderWidth={3}
  segmentSpacing={2}
  segmentHeight={60} //android only
  activeFieldBorderColor="#ff0000"
  inactiveFieldBorderColor="#00ffff"
/>;

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

Password - SecurePasswordTextField​

Password complexity​

Validate password​

Submit password​

Using the component​

Set the user token in the SDK​

Check if an association exists with the SDK​

Passcode - SecurePasscodeTextField​

Frequently asked questions​

Choosing a login approach

Tokenised login (preferred)

Non-tokenised login

Where each component fits in your login screen