Skip to main content

Invite additional users

Every identity is created with a single root user as part of corporate or consumer onboarding. This guide covers adding further users to an existing identity-from creating the user, through setting their password, to enrolling an authentication factor.

Who's who​

To avoid ambiguity, this guide uses the following terms:

  • You-the embedderEmbedder A company or developer that integrates Weavr's embedded finance services into their own application to provide financial services to their end customers. integrating Weavr. You call the Weavr APIs from your backend.
  • Acting user-the existing user on whose behalf you are creating a new authorized userAuthorized User An individual that has been invited by the root user to manage an identity's instruments and transactions. They are not the legal owner of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_.. The acting user must be authenticated and hold the Admin or Access Management role. You perform the create and invite operations using the acting user's access token.
  • New user-the new authorized userAuthorized User An individual that has been invited by the root user to manage an identity's instruments and transactions. They are not the legal owner of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_. being onboarded. They do not yet have credentials; steps 2 and 3 set those up.

For background, see the definitions of authorized user and stepped-up token in the glossary.

Prerequisites​

  • An existing user on the identity (this will be your acting user)
  • User communications set up - only required if you plan to use the user invitation flow

Steps​

  1. Step-up the acting user.
  2. Create a new user.
  3. Set the new user's password - either via the create-password API or via the user invitation flow.
  4. Enroll the new user's device for an additional authentication factor.
Assign the right role

We provide a set of pre-configured roles that you can assign to users to control their level of access. Review user roles to pick the role that matches each new user's function. If you are running a program where corporatesCorporates Business entities that can be onboarded as identities on Weavr. Corporate identities represent companies and require Know Your Business (KYB) verification. They can have multiple authorised users and issue cards to card assignees. issue cards, the card user must be created as an authorized userAuthorized User An individual that has been invited by the root user to manage an identity's instruments and transactions. They are not the legal owner of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_. (typically with the Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users. role) and linked to the card before it can be used.

1. Step-up the acting user​

Creating a user is a sensitive operation, so the acting user's access token must be stepped-up before you call this endpoint. In outline:

  1. Issue a step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. for the acting user.
  2. Verify the challenge with the OTP the acting user receives.
  3. Use the resulting 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. on the POST /users call.

For the full sequence, see the step-up authentication guide.

2. Create a new user​

Call the create-user API, authenticated as the acting user, to create a new user against the acting user's identity:

POST/usersTry it 
{
  "name": "string",
  "surname": "string",
  "email": "[email protected]",
  "mobile": {
    "countryCode": "stri",
    "number": "string"
  },
  "dateOfBirth": {
    "year": 1900,
    "month": 1,
    "day": 1
  },
  "tag": "string"
}

Required fields​

When creating an authorized userAuthorized User An individual that has been invited by the root user to manage an identity's instruments and transactions. They are not the legal owner of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_., provide the basic personal information needed for financial operations. mobile and dateOfBirth are optional in the API, but both become mandatory before the new user can be assigned and use a card. The user can also set their mobile number themselves during the user invitation flow described in step 3.

The response includes the new user's id, which you use to identify them in subsequent API calls.

Tagging users​

Authorized usersAuthorized User An individual that has been invited by the root user to manage an identity's instruments and transactions. They are not the legal owner of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_. can multiply in programs with lots of card assigneesCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.. You may want to manage interactions and data around authorized usersAuthorized User An individual that has been invited by the root user to manage an identity's instruments and transactions. They are not the legal owner of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_. - an optional tag field lets you store custom information against those records.

The authorized userAuthorized User An individual that has been invited by the root user to manage an identity's instruments and transactions. They are not the legal owner of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_. tag can be included in API calls as follows:

  • POST /users
  • GET /users
  • PATCH /users/{user_id}

The tag is also available when filtering authorized usersAuthorized User An individual that has been invited by the root user to manage an identity's instruments and transactions. They are not the legal owner of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_. 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..

3. Set the new user's password​

The new user must set up their password. You can do this in two ways:

  • Create-password API - if the new user is already using your product.
  • User invitation flow - if the new user still needs to start using your product.

Via the create-password API​

If the new user is already using your product, use this option to quickly set their 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.

Via the user invitation flow​

Set up user communications first

The invitation email is part of our user communications. Before you send invites in production, make sure you have configured your sender email address and, if relevant, customized your email templates.

If the new user is not yet using your product, use the invitation flow to start onboarding them. The invitation flow has two steps:

  1. You send an invitation email to the new user.
  2. The new user accepts the invitation and provides their password.
Setting user mobile number

If the user's mobile phone number is not known at the point of user creation, or if you want the user to confirm it themselves, they can provide it when they accept the invite. It is then sent to Weavr when the invite is consumed.

Call the send-user-invite API to send the invitation email:

POST/users/{user_id}/inviteTry it 
{
  "code": "string",
  "message": "string"
}

The invitation email includes a URL that redirects to your app. Build a page in your app for this URL to land on, where the new user can enter the verification code from the email.

info

The invitation expires after 30 days.

Set the new user's password by submitting the verification code together with the new user's chosen password. You can also provide the user's mobile phone number at the same time, if it was not set during user creation:

POST/users/{user_id}/invite/consumeTry it 
{
  "inviteCode": "string",
  "password": {
    "value": "pa$$word"
  }
}

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

4. Enroll the new user's 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"
}

Enroll for biometric authentication​

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.