Advanced Implementation

The following are optional implementation steps that can be taken to optimize the branding, streamline the end customer experience, and provide access to richer functionality.

Theming

To match your branding, you can customize colors, logos, fonts, etc. Refer to our theming guide.

The White-Label App can be styled by passing a theme object to the settings-json attribute.

You can also demo these changes using the branding page in your Sandbox Dashboard.

Pre filling end-user information

1-2 days

If you have access to end customer information that you can share in order to streamline their onboarding onto banking and can reduce the friction of submitting the application, we allow you to provide it and we will use it to pre-fill the end customer’s application form. To support that, you will have to expose an API endpoint that Unit will call when seeing an end user (identified by their JWT subject) for the first time.

Unit will make an HTTP request to this endpoint with a JWT token associated with this user in the Authorization header before initiating the end customer application process. The server will need to return the End User Configuration resource. The response must include the data, type: whiteLabelAppEndUserConfig and attributes keys.

Please contact Unit in order to configure the endpoint.

Request example:

curl -X GET 'https://yourdomain.com/unit/application-form-prefill' \
-H "Authorization: Bearer ${JWT Token}"

Inviting additional users to Banking

1-2 days

In order to allow more than one end user of yours access to the same banking experience (e.g. two employees of the same business, represented as two separate JWT subjects on your platform), The user that applies for banking, once approved, needs to be able to invite additional users.

Since Unit isn’t familiar with the relationship between users on your platform, we rely on you to tell us who the users are that another user may grant access to, by providing an API endpoint we can call, that returns a list of users, represented as JWTs.

Unit relies on you to manage and define user roles effectively. Below are the responsibilities and requirements for user management and role assignment within the Ready-to-Launch Banking App.

Role Assignment via JWT Token​

Each user in Ready-to-Launch Banking has an assigned role, which your backend is responsible for managing. The end customer can create users in the White-Label App and assign roles to them. To update a user’s role, include the new role in a unitRole attribute in the JWT token. Unit validates the JWT token on a user login: if a role is provided in the token, Unit will update the user’s role in the White-Label App accordingly. If a role is not provided in the JWT token, Unit will retain the last role that was sent.

Allowed Roles​

The only allowed roles are Admin and ReadOnly. If you include a role other than these in the JWT token, the request will fail.

Managing End Users​

The White-Label App provides functionality for creating, removing, and listing users within the app. The customer can manage all types of users. Admin can only manage users who has ReadOnly permissions. To enable these capabilities, you will need to implement an API endpoint that returns a list of your app's existing end-users.

API Endpoint Requirements​

Request:​ Unit will send an HTTP request to the API endpoint that you will implement, including a JWT token in the Authorization header.

curl -X GET 'https://yourdomain.com/unit/users' \
-H "Authorization: Bearer ${JWT Token}"

Response:​ The API must return a list of end-users associated with the customer resource created at Unit. Each end-user in the list should be represented as an object and include their unique JWT subject. By adhering to these guidelines, you will ensure consistent user role management within the White-Label App.

Field	Type	Description
fullName	FullName	Full name of the end user.
email	string	Email address of the end user.
phone	Phone	Phone number of the end user.
jwtSubject	string	Unique string identifying the end user.
unitRole	string	The role of the end user. Can be either Admin or ReadOnly.
bankingPageURL	string	Optional. URL to the banking page on the client’s website (For linking via email).

Example whiteLabelAppEndUser type:

[
  {
    "data": {
      "type": "whiteLabelAppEndUser",
      "attributes": {
        "fullName": {
          "first": "Peter",
          "last": "Parker"
        },
        "email": "peter.parker@parker.com",
        "phone": {
          "countryCode": "1",
          "number": "2345678888"
        },
        "jwtSubject": "test",
        "unitRole": "Admin"
      }
    }
  },
  {
    "data": {
      "type": "whiteLabelAppEndUser",
      "attributes": {
        "fullName": {
          "first": "April",
          "last": "Oneil"
        },
        "email": "april.oneil@parker.com",
        "phone": {
          "countryCode": "1",
          "number": "2345678899"
        },
        "jwtSubject": "test2",
        "unitRole": "ReadOnly"
      }
    }
  }
]

After the endpoint has been implemented on your side, please contact Unit in order to configure it.

Custom JWT Authentication

3-4 hours

Unit can rely on a custom implementation of JWT token that adheres to the specifications outlined in RFC 7519.

In this case you should provide Unit with a public key that will be used to validate the token.

The token must be signed using the RS256 algorithm and must include the following claims:

Claim	Description
sub	A unique identifier for the end-user
exp	The expiration time of the token
iss	The issuer of the token

JWT Authentication Troubleshooting:

If you receive an error, ensure the following:

• You're using the Sandbox (ui.s.unit.sh) or Production (ui.unit.co) script matching your environment.
• Decode your token. The iss matches the Issuer you configured in the Dashboard and the sub value is a string (stable user id). The token is still valid, with an exp in the future. The header includes alg: RS256 and a valid kid.
• The Public Key was entered into the Unit Dashboard correctly, and is the correct one for the provided token. The kid in the JWT matches one in your uploaded Public Key or JWKs.
• The cache has been cleared (localStorage keys unitCustomerToken and unitVerifiedCustomerToken).
• The jwt-token value is present before the component initializes.