Returning users experience

User tokens are essential to preserve sessions for users and avoid duplicate account connections.

Overview

The user token is a necessary tool to create a seamless returning user experience and prevent duplicate account connections. User tokens are temporary access keys that allow you to take users to the correct spot within the Argyle flow. Whenever you need a user to return to Argyle Link, you have to utilize user tokens in the Link configuration.

Users

Argyle refers to your customers (loan applicants, potential bank account holders, etc.) as users. Users interface with Argyle Link to connect their payroll accounts or update their pay distributions.

Use cases

User tokens are required to:

Direct users to re-authenticate

Some platforms have connection timeouts or force log out if users log in on another device. In these cases, users need to log into their payroll platform again to keep the account connection active.

The user token allows Link to restore the previous session and take users directly to the Login screen.

Direct users to confirm a pay distribution update

You can have users connect their payroll accounts, return to your app for additional steps, and then return to Argyle to confirm a pay distribution update. This use case is relevant if you are utilizing Argyle for paycheck-linked lending or similar solutions.

Direct users to manage their connected accounts

Likewise, you can direct users to manage their account connections, where they can revoke the access, connect more accounts (e.g. when auser has more than one job), update pay distribution, etc.

Direct users to complete MFA

An additional multi-factor authentication (MFA) step can be required when users are confirming their pay allocation/distribution or removing allocations directly via API. In such cases, you can send the user directly to the MFA screen.

User tokens prevent duplicate account connections

If the user token is absent, Link does not recognize the previously connected user and creates a duplicate account for them. The data is identical in the two accounts but they are treated as two separate connected accounts, as Argyle treats all the accounts agnostically.

Check how the single charge upon account connection works.

When to utilize user tokens

Argyle strongly recommends user tokens as the best practice for all cases, especially if you expect your users to return to Link. Unless you are performing a specific one-time connection or want to prevent a user from returning to Link, you should utilize user tokens.

Suggested flow for user token usage

Link generates the token as a consequence when the user connects an account. This is the most common approach to creating users and generating user tokens.

When connecting a new user:

  1. Initialize Link with your configuration.
  2. Include the onUserCreated callback.
  3. Save the userId and userToken that are sent by the callback.

When the same user is returning to Link, check if userToken has not expired and is still valid:

  • If userToken is still valid, provide it to Link in the config.
  • If userToken has expired:
    • Create a new userToken by calling the /user-tokens endpoint in the Argyle API to generate a new userToken.
    • Provide it to Link in the config. Make sure that you request user tokens on your server-side and your client_id and client_secret are never exposed on the front-end.

IfuserToken is absent, every time a user tries to connect an account (successfully or not), Link emits a new userToken (via onUserCreated).

However, the most important information here is the userId. With userId, you can associate the user on Argyle's side to the user on your platform.

If you know userId, you can skip saving userToken and generate a new one before the next Link session. If you prefer to save userToken and utilize it later to resume some session, it is necessary to check for validity, as tokens have an expiry date.

Creating users on the back-end via API

If your system requires that you create users in advance on the back-end via the API, you already have a userId and a userToken. When the user is entering Link for the first time, check if userToken has not expired and is still valid:

  • If userToken is still valid, provide it to Link in the config.
  • If userToken has expired:
    • Create a new userToken by calling the /user-tokens endpoint in the Argyle API to generate a new userToken.
    • Provide it to Link in the config. Make sure that you request user tokens on your server-side and your client_id and client_secret are never exposed on the front-end.

User tokens expiration

User tokens are JWT tokens that contain an expiration date. You can always decode the token to discover the exact expiration date (check exp field).

As mentioned in the suggested flow section, the user token expiration must be checked every time you initiate Link.