Set up the root user

"Identities" are now "Customers"

We used to refer to the representation of your customer in the Weavr system as an identity. We now just call them a customer. The two mean the same thing — you may still see identity in some API fields and older pages.

When you create a customer (corporate or consumer), its root user is created in the same call but is not yet ready to operate. This guide walks through activating the initial user so they can complete due diligence and use the customer.

These steps are common to both corporate and consumer customers; the email verification endpoint differs by customer type and is shown side by side here.

Prerequisites

• A customer has been created via POST /corporates or POST /consumers. The response includes the root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user.'s id.

Steps

1. Set the root user's password.
2. Verify the root user's email address.
3. Enroll the root user's mobile device.
4. Enroll an alternative authentication factor (optional).

Once these steps are complete, the root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user. can proceed to KYC or KYB.

1. Set the root user's password

To set the user's password, call the create-password API. This is a different API from the one used to create the user.

POST/passwords/{user_id}/createOpen API reference →

/passwords/987654321/create

{  "password": {    "value": "Passw0rd!"  }}

Non-PCI-compliant integrators

If you are not PCI-compliant, you cannot handle your customers' plain-text passwords. Instead, you must tokenizeTokenizeReplace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. passwords. For more information, see the tokenization guide.

The response includes a token. Provide this token on subsequent API calls that require the user to be logged in.

2. Verify the root user's email address

The root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user. must verify their email address before due diligence can start. Without it, they cannot initiate the KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. or KYBKYB (Know Your Business). Know Your Business - the identity verification process for corporate customers. This process allows you to securely verify your business customer's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. flow.

You can start the verification process using the API. The root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user. receives an email at the address you provided when you created the customer.

No authentication required for this request

To send the verification email, the root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user. does not need to be authenticated.

Corporate

POST/corporates/verification/email/sendOpen API reference →

/corporates/verification/email/send

{  "email": "[email protected]"}

Consumer

POST/consumers/verification/email/sendOpen API reference →

/consumers/verification/email/send

{  "email": "[email protected]"}

Handle the verification link

After you start email verification, the root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user. receives an email message that contains a URL. You must create a page in your app to which this URL points. On this page, the root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user. inputs the verification code they received in the email.

Configure your app's base URL

For the email verification to work, you need to configure your app's base URL in Programme settings.

The email verification link is valid for 60 minutes from the moment verification is triggered. During this time, the user can continue to authenticate via the Weavr login (in case your page is behind a login). A user can trigger a new email verification link within those 60 minutes, and the new link is valid for another 60 minutes.

If the user does not verify their email via the link, they cannot initiate the due diligence process.

If a user does not verify their email (for example, the link expires), the system marks them as ABANDONED. The portal still shows these users as INACTIVE, with ABANDONED shown in the side panel as the reason.

If an ABANDONED user registers again with the same email address (and completes the verification), the user becomes ACTIVE and is automatically updated from the ABANDONED state.

Submit the verification code

Verify the email address by submitting the verification code that the root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user. received in the email and then submitted to your app.

Corporate

POST/corporates/verification/email/verifyOpen API reference →

/corporates/verification/email/verify

{  "email": "[email protected]",  "verificationCode": "123456"}

Consumer

POST/consumers/verification/email/verifyOpen API reference →

/consumers/verification/email/verify

{  "email": "[email protected]",  "verificationCode": "123456"}

3. Enroll the root user's mobile device

The user must enroll at least one additional authentication factor to perform step-up authentication for operations that require Strong Customer Authentication (SCASCA (Strong Customer Authentication). Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics).). Enrolling SMS as an authentication factor can be done in two ways:

1. As a standalone action, described below.
2. As part of the biometrics enrollment process - see the following section.

One device at a time

A user can only be enrolled on a single device at a time. This is a hard constraint of the SMS authentication factor - a verification code is sent to one mobile number, which in turn lives on one device. Biometric enrollment, which builds on top of SMS, inherits the same limitation.

If the user re-enrolls on a new device, the previous device's enrollment is invalidated. Plan for this in your UX:

• Don't expose flows that imply parallel enrollment across phone, tablet, or other devices.
• When supporting device replacement, treat it as a fresh enrollment and surface a clear "this will sign you out of your other device" message.
• For biometrics, you can unlink the previous device explicitly through the Authentication Factors unlink endpoint - see the un-enrollment guidance for details.

Send the SMS verification code

Start the enrollment process using the API. The user receives a text message (SMS) at the mobile number provided when the user was created.

User must be authenticated

To send the enrollment text message, the user must be authenticated.

POST/authentication_factors/otp/{channel}Open API reference →

/authentication_factors/otp/SMS

Verify the mobile device

Build a page in your app where the user can enter the verification code they received in the text message. Submit the verification code using the API:

Challenge expiry and attempt limits

To verify the verification code, the user must be authenticated. The challenge expires after 5 minutes and the number of incorrect OTP attempts is limited to reduce the risk of fraud; the challenge remains in a Pending state until the last incorrect attempt has been consumed within the 5 minutes. A successful verification also steps up the user's current session, allowing access to the endpoints that require a stepped-up tokenStepped-up tokenAn access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge..

POST/authentication_factors/otp/{channel}/verifyOpen API reference →

/authentication_factors/otp/SMS/verify

{  "verificationCode": {}}

4. Enroll an alternative authentication factor

We offer additional authentication methods other than SMS. If you have a mobile app, we offer an embeddable Biometrics Authentication component as an SDK. The enrolled authentication method is used instead of SMS once enrollment is complete.

Biometric enrollment also enrolls SMS

Enrollment for biometrics is initiated directly from the SDK; see enrolling a device for details. The enrollment flow includes an SMS OTP that also automatically enrolls SMS as an authentication factor for the user, so you don't need to complete SMS enrollment separately.

Activate biometrics in the portal first

Biometrics must be activated in the embedder portalEmbedder PortalA web-based portal where embedders manage their Weavr account: browse customers and instruments, configure programmes, find API credentials and profile IDs, run Sandbox simulations, and inspect webhook deliveries. Sandbox and Live are separate, with their own credentials and data., under Settings > Authentication configs > Biometric, before users can be enrolled to this authentication method.