Skip to main content

Set up the root user

When you create an identity (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 root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. so they can complete due diligence and use the identity.

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

Prerequisites​

  • An identity has been created via POST /corporates or POST /consumers. The response includes the root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity 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 user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity 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}/createTry it 
{
  "password": {
    "value": "pa$$word"
  }
}
Non-PCI-compliant integrators

If you are not PCI-compliant, you cannot handle your customers' plain-text passwords. Instead, you must tokenizeTokenize Replace 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 user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity 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 - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. or KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. flow.

You can start the verification process using the API. The root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. receives an email at the address you provided when you created the identity.

info

To send the verification email, the root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. does not need to be authenticated.

POST/corporates/verification/email/sendTry it 
{
  "email": "[email protected]"
}

After you start email verification, the root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity 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 user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity 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. For more information, see App base URL (corporate) or App base URL (consumer).

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 user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. received in the email and then submitted to your app.

POST/corporates/verification/email/verifyTry it 
{
  "email": "[email protected]",
  "verificationCode": "string"
}

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 - 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.

info

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

POST/authentication_factors/otp/{channel}Try it 
{
  "code": "string",
  "message": "string"
}

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:

info

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 token An 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}/verifyTry it 
{
  "verificationCode": "string"
}

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.

tip

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.

info

Biometrics must be activated in the embedder portalEmbedder Portal A web-based portal where embedders can access their Weavr account, manage API credentials, configure settings, view dashboards, and access documentation. The portal provides access to both sandbox and production environments, with separate credentials for each. before users can be enrolled to this authentication method.