Login (Web SDK)

Before your customers can access their cards and managed accounts, they must be onboarded and authenticated on our platform. The login components capture credentials securely and convert them into one-time-use tokens that you can safely send to our API.

We support two login factors:

• Password — at least 8 alphanumeric and symbol characters
• Passcode — 4 digits, suitable when your app already authenticates the user with another factor

Each factor has a paired confirm component that validates the value entered in a second field matches the first. Use confirm components during sign-up and password change flows.

Where each component fits in your login screen

The login components each render one credential field inside a tokenized iframe. The mockup below shows where they typically appear in your app — hover the numbered hotspots for the underlying API calls.

Option A

your app

Set your password

Used to sign in next time

Password

••••••••

1form.input("password", "password")PasswordCaptures the user's password inside a tokenised secure field, returning a one-time use token.Jump to docs →

Confirm password

••••••••

2form.input("confirmPassword", "confirmPassword")Confirm passwordPairs with the password field — checks that two entered passwords match before tokenising.Jump to docs →

Continue

or

Option B

your app

Set your passcode

Used to sign in next time

Passcode

••••

1form.input("passcode", "passCode")PasscodeCaptures a numeric passcode (typically 4 digits) for a 'something you know' factor.Jump to docs →

Confirm passcode

••••

2form.input("confirmPasscode", "confirmPassCode")Confirm passcodePairs with the passcode field — checks that two entered passcodes match before tokenising.Jump to docs →

Continue

Password and passcode are alternatives — pick one for your app. Each is paired with its confirm component, which validates the value entered in the second field matches the first. Hover or focus a numbered hotspot to see the underlying API call.

tip

To use our UI components, you must first set up the SDK in your app.

Password

The Password component collects your customer's password securely and converts it into a token, which you can safely send to Weavr using the API.

warning

Due to requirements related to strong customer authentication, your authentication token must be stepped-up when calling this component to update an existing password.

<form onSubmit="onSubmit(); return false;">
  Username: <input type="input" name="u" /><br />
  Password:
  <div id="password"></div>
  <br />
  <input type="submit" value="Login" />
</form>

<script type="text/javascript">
  window.OpcUxSecureClient.init("YOUR_UI_KEY");

  var form = window.OpcUxSecureClient.form();

  // The first argument is the field name used as the token key when tokenize() is called.
  var input = form.input("password", "password", {
    placeholder: "Password",
    maxlength: 30,
  });
  input.mount(document.getElementById("password"));

  // Pressing the enter key in the password input triggers the submit handler
  input.on("submit", () => {
    console.log("submit password input");
  });

  function onSubmit() {
    form.tokenize(function (tokens) {
      console.log(tokens);
    });
  }
</script>

Authenticate the user

With the tokenized password, authenticate the user from your server.

caution

You must perform this step on the server side of your app.

POST/login_with_passwordTry it

Request

{
  "email": "[email protected]",
  "password": {
    "value": "pa$$word"
  }
}

Response

{
  "token": "string",
  "tokenType": "NO_TYPE",
  "identity": {
    "type": "CONSUMER",
    "id": "string"
  },
  "credentials": {
    "type": "ROOT",
    "id": "string"
  }
}

After a successful login, the response includes a token field. Use this token to authenticate the user in subsequent API calls.

Confirm password

The Confirm password component pairs with the Password component to validate that two entered passwords match. Use it during sign-up and password change flows.

info

The confirm password component requires the password component to be mounted in the same form.

<form onSubmit="onSubmit(); return false;">
  <label>Password Confirmation</label>
  <div id="input-password"></div>
  <br />
  <div id="input-password-confirm"></div>
  <br />
  <input type="submit" value="confirm" />
</form>
<div id="inputPasswordConfirmResponse"></div>

<script type="text/javascript">
  window.OpcUxSecureClient.init("YOUR_UI_KEY");

  const form = window.OpcUxSecureClient.form();

  const password = form.input("password", "password", {
    placeholder: "Password",
  });
  const confirmPassword = form.input("confirmPassword", "confirmPassword", {
    placeholder: "Confirm Password",
  });

  password.mount("#input-password");
  confirmPassword.mount("#input-password-confirm");

  function onSubmit() {
    // tokenize checks the passwords match before tokenizing
    form.tokenize(
      (res) => {
        document.getElementById("inputPasswordConfirmResponse").innerText =
          JSON.stringify(res);
      },
      (err) => {
        console.error("Error:", err.message);
        document.getElementById("inputPasswordConfirmResponse").innerText =
          "ERROR: " + JSON.stringify(err);
      }
    );
  }
</script>

Passcode

If your app already authenticates the user with another factor, you can use a 4-digit passcode in place of a password.

info

Contact our support team if you're interested in setting up your app to use passcodes instead of passwords.

warning

Due to requirements related to strong customer authentication, your authentication token must be stepped-up when calling this component to update an existing passcode. Step-up isn't required for initial passcode creation during onboarding.

<form onSubmit="onSubmit(); return false;">
  Username: <input type="input" name="u" /><br />
  Passcode:
  <div id="passcode"></div>
  <br />
  <input type="submit" value="Login" />
</form>

<script type="text/javascript">
  window.OpcUxSecureClient.init("YOUR_UI_KEY");

  var form = window.OpcUxSecureClient.form();

  var input = form.input("passcode", "passCode", {
    placeholder: "Pass Code",
  });
  input.on("submit", () => {
    onSubmit();
  });

  input.mount(document.getElementById("passcode"));

  function onSubmit() {
    form.tokenize(function (tokens) {
      console.log(tokens);
    });
  }
</script>

Authenticate the user

The login API endpoint is the same for password and passcode — you exchange the tokenized credential for a session token from your server.

caution

You must perform this step on the server side of your app.

POST/login_with_passwordTry it

Request

{
  "email": "[email protected]",
  "password": {
    "value": "pa$$word"
  }
}

Response

{
  "token": "string",
  "tokenType": "NO_TYPE",
  "identity": {
    "type": "CONSUMER",
    "id": "string"
  },
  "credentials": {
    "type": "ROOT",
    "id": "string"
  }
}

Confirm passcode

The Confirm passcode component pairs with the Passcode component to validate that two entered passcodes match.

info

The confirm passcode component requires the passcode component to be mounted in the same form.

<form onSubmit="onSubmit(); return false;">
  <label>Passcode Confirmation</label>
  <div id="input-passcode"></div>
  <br />
  <div id="input-passcode-confirm"></div>
  <br />
  <input type="submit" value="confirm" />
</form>
<div id="inputPasscodeConfirmResponse"></div>

<script type="text/javascript">
  window.OpcUxSecureClient.init("YOUR_UI_KEY");

  const form = window.OpcUxSecureClient.form();

  const passcode = form.input("passcode", "passCode", {
    placeholder: "Passcode",
  });
  const confirmPasscode = form.input("confirmPasscode", "confirmPassCode", {
    placeholder: "Confirm Passcode",
  });

  passcode.mount("#input-passcode");
  confirmPasscode.mount("#input-passcode-confirm");

  function onSubmit() {
    // tokenize checks the passcodes match before tokenizing
    form.tokenize(
      (res) => {
        document.getElementById("inputPasscodeConfirmResponse").innerText =
          JSON.stringify(res);
      },
      (err) => {
        console.error("Error:", err.message);
        document.getElementById("inputPasscodeConfirmResponse").innerText =
          "ERROR: " + JSON.stringify(err);
      }
    );
  }
</script>