Installation

Install the SDK using npm or yarn.

npm install @moneytree/mt-link-javascript-sdk

# or

yarn add @moneytree/mt-link-javascript-sdk

Then you can use it directly in your code:

Usage:

// using import
import mtLinkSdk, { MtLinkSdk } from '@moneytree/mt-link-javascript-sdk';

// or using require
const { default: mtLinkSdk, MtLinkSdk } = require('@moneytree/mt-link-javascript-sdk');

// or via window object
const instance = window.mtLinkSdk;
const newInstance = new window.MtLinkSdk();

// mtLinkSdk - an instance of the SDK.
// MtLinkSdk - in case you need to create a new instance of the SDK for whatever reason,
//             e.g: const newInstance = new MtLinkSdk();

Typscript

The source also includes Typescript definition out of the box.

Polyfills

We use fetch and Promise internally, if you wish to support old browsers (e.g: IE11), make sure to add the necessary polyfills.

API

SDK offers various APIs below to help from getting guest consent via authorization to exchange for a token to access guest financial data.

init

SDK initialization method, it is not necessary to call init to use some of the APIs.

APIs that requires beforehand init call are usually related to OAuth and requires a client id which can only be set via the init parameter. These APIs are listed below:

authorize
onboard
exchangeToken
tokenInfo

Usage:

mtLinkSdk.init(clientId, options);

Parameter	Type	Required	Default Value	Description
clientId	string	true		OAuth `clientId` of the app (please request this from your Moneytree representative if you need one). NOTE: SDK will throw an error if none was provided.
options	object	false		This options includes all the value below and also every `options` parameters of the other APIs, options values passed here during initialization will be used as the default value of other APIs in cases where no value was passed when calling the other APIs. The options are authorize options and common options; refer to each individual links for more details.
options.mode	`production`, `staging`, `develop`, `local`	false	`production`	Environment for the SDK to connect to, the SDK will connect to Moneytree production server by default. For Moneytree client, please use `staging` for development as `develop` will contain unstable features. `local` should only be used for SDK development as it requires various setup locally.
options.locale	string	false	Auto detect.	Force Moneytree to load content in this specific locale. A default value will be auto detected based on guest langauges configurations and location if available. Check this spec for more information. Currently supported values are: `en`, `en-AU`, `ja`.
options.cobrandClientId (private)	string	false		NOTE: this is for Moneytree internal use, please do not use it to avoid unintended behavior! Brand Moneytree apps with client's branding. E.g: logo or theme.

authorize

OAuth authorization method to request guest permission to allow data access via Link API.

Guest login are required for this to work, by default we will show the login screen and redirect the guest to the consent screen after they login (Redirection happened immediately if their existing session exists, you can refer this option below to force logout an existing guest session).

You can also change to display sign up instead of login screen as default by setting this option.

NOTE: Please remember to call init beforehand.

Usage:

mtLinkSdk.authorize(options);

Parameter	Type	Required	Default Value	Description
options	object	false	Value set during `init`.	Optional parameters. Includes all options in common options.
options.scopes	string OR string[]	false	Value set during `init`. OR `guest_read`	Scopes of access permissions, can be one or an array of the below scopes. Currently supported scopes are: `guest_read`, `accounts_read`, `points_read`, `point_transactions_read`, `transactions_read`, `transactions_write`, `expense_claims_read`, `categories_read`, `investment_accounts_read`, `investment_transactions_read`, `notifications_read`, `request_refresh`, `life_insurance_read`.
options.redirectUri	string	false	Value set during `init`.	OAuth redirection uri, refer here for more details. NOTE: SDK will throw an error if both values here and from the init options are undefined.
options.state	string	false	Value set during `init`. OR Randomly generated uuid.	Refer here for more details. NOTE: Make sure to set this value if your server are generating the value from the server and is redirecting back to your server so that your server can use it to exchange for a token.
options.codeVerifier	string	false	Value set during `init`. OR Randomly generated uuid.	For security reasons we removed support of using implicit flow instead opting to use PKCE/code grant. We only support SHA256, hence this `codeVerifier` will be used to generate the `code_challenge` using SHA256 encoding method. Refer here for more details. NOTE: Make sure to set this value if your server are generating the value from the server and is redirecting back to your server so that your server can use it to exchange for a token.
options.forceLogout	boolean	false	`false`	Force existing guest session to logout and call authorize with a clean state.
options.country	`AU`, `JP`	false	Value set during `init`.	Server location for the guest to login or sign up. If you wish to restrict your guest to only one country, make sure to set this value. NOTE: For app created after 2020-07-08, the sign up form will display a country selection dropdown for the guest to choose when this value is undefined or invalid.

onboard

Onboard allows a new guest to get onboard faster to use an app without having to go through the registration process. All you have to do is provide an email with all the same configuration as authorize method options, we will then show them a consent screen explaining all the details, the moment a guest gave their approval, a new Moneytree account will be created on their behalf and authorization is completed. Resulting behavior will be the same as authorize redirection flow.

Onboard will force all current guest session to logout, hence you do not have to call logout manually to ensure a clean state.

If an account with this email existed, we will redirect the guest to the login screen.

NOTE:

Please remember to call `init` beforehand.

For legal reason, you will have to setup your app's terms and condition link to use the onboard feature (please consult your Moneytree representative).

Usage:

mtLinkSdk.onboard(options)

Parameter	Type	Required	Default Value	Description
options	object	false	Value set during `init`.	Optional parameters. All the supported options are the same as authorize method options and common options except the options in the following list. Not supported options from authorize and common options are: forceLogout authAction showAuthToggle showRememberMe
options.country	`AU`, `JP`	true	Value set during `init`.	Server location for the guest to login or sign up. NOTE: SDK will throw an error if both values here and from the init options are undefined.
options.email	string	true	Value set during `init`.	A new Moneytree account will be created with this email, if an existing account with this email exists, the guest will be redirected to login screen. NOTE: SDK will throw an error if both values here and from the init options are undefined.

exchangeToken

Since we are using PKCE/Code grant, we will have to exchange the code for a token. You can optionally pass code via options parameter or it will fallback to automatically extract it from the browser URL.

By default options values for state, codeVerifier and onboard will used the default value from init, however if you explicitly passed a new value when calling authorize or onboard via the options parameter, make sure to reuse the same value when calling this API or else authentication server will throw an error because the values does not matched.

If there is a state passed via this API option (or it exists in the URL), it will be used internally to compared to the state used in the previous authorize or onboard call during the same session, this API will throw an error when both states does not matched. Refer here for more details.

code will be invalidated (can be used only once) after exchanged for a token, it is your responsibility to store the token yourself as the SDK do not store it internally.

Refer here for more details.

Usage:

One way to use this API is by calling it in the redirected page script. For example, if authorize redirect to https://yourapp.com/callback?code=somecode, you can call this API in the script loaded by the redirected URL and the API will automatically extract the code to exchange for a token.

Alternatively, you can extract the code manually from the redirected URL and pass it to this API as options anywhere in your codebase as you wish.

const token = await mtLinkSdk.exchangeToken(options);

Parameter	Type	Required	Default Value	Description
options	object	false	Value set during `init`.	Optional parameters.
options.code	string	false	Value from browser URL	Code from OAuth redirection used to exchange for a token, SDK will try to extract it from the browser URL if none was provided. NOTE: SDK will throw an error if no value was provided here or failed to extract from browser URL.
options.state	string	false	Value set during `init`.	Make sure the value of `state` here is the same state value used during `authorize` or `onboard` call.
options.codeVerifier	string	false	Value set during `init`.	Make sure the value of `codeVerifier` here is the same state value used during `authorize` or `onboard` call.
options.redirectUri	string	false	Value set during `init`.	Make sure the value of `redirectUri` here is the same state value used during `authorize` or `onboard` call. NOTE: SDK will throw an error if both values here and from the init options are undefined.

tokenInfo

You can validate a token or get guest or resource server information related to the token by calling this API.

NOTE: this API will throw an error if the token was expired.

Usage:

const tokenInfo = await mtLinkSdk.tokenInfo(token, options);
tokenInfo.guestUid // guest's uid
tokenInfo.country // guest's country
tokenInfo.currency // guest's currency
tokenInfo.language // guest's language
tokenInfo.resourceServer // resource server domain
tokenInfo.clientId // app client id
tokenInfo.clientName // app name
tokenInfo.expTimestamp // token expiration timestamp
tokenInfo.scopes // token access scopes
tokenInfo.isMtClient // for internal use

Parameter	Type	Required	Default Value	Description
token	string	true		Token you wish to get info of.
options	object	false	Value set during `init`.	Optional parameters.
options.redirectUri	string	false	Value set during `init`.	Make sure the value of `redirectUri` here is the same state value used during `authorize` or `onboard` call. NOTE: SDK will throw an error if both values here and from the init options are undefined.

logout

Logout current guest from Moneytree.

Usage:

mtLinkSdk.logout(options);

Parameter	Type	Required	Default Value	Description
options	object	false	Value set during `init`.	Optional parameters. Includes all options in common options.

openService

This is a method to open various services provided by Moneytree such as Moneytree account settings and Vault etc.

NOTE: calling this API before calling init will open the services without branding (no company logo etc.).

Usage:

mtLinkSdk.openService(serviceId, options);

Parameter	Type	Required	Default Value	Description
serviceId	`vault`, `myaccount-settings`, `link-kit`	true		Open a service by Id, current supported services are: `vault` - A service to set your banks credentials. `myaccount-settings` - Display screens too change your Moneytree account settings. `link-kit` - A service to view all your financial data. NOTE: SDK will throw an error if none was provided.
options	object	false	Value set during `init`.	Optional parameters. Includes all options in common options.

requestMagicLink

Request for a magic link (password-less link) sent to guest email, clicking on the link in the email will log a guest in directly to the screen as indicated by the parameter.

Usage:

mtLinkSdk.requestMagicLink(options);

Parameter	Type	Required	Default Value	Description
options	object	false	Value set during `init`.	Optional parameters. Includes all options in common options.
options.magicLinkTo	string	true	`settings` (for mobile view) OR `settings/update-email` (for desktop view)	Redirection to location after login, current supported location are: `settings` - Root Moneytree account settings screen. `settings/authorized-applications` - List of apps currently connected to Moneytree screen. `settings/change-language` - Change Moneytree account language screen. `settings/email-preferences` - Change Moneytree email preferences screen `settings/delete-account` - Delete Moneytree account screen `settings/update-email` - Change Moneytree account email screen `settings/update-password` - Change Moneytree account password
options.email	string	true	Value set during `init`.	Magic link will be sent to this email. NOTE: SDK will throw an error if both values here and from the init options are undefined.

Common API options

Common options are options that is used by multiple APIs. Instead of repeating the same documentation in every APIs, we will link refer them to here.

NOTE: Since options are optional, SDK will read from init options by default if none was provided.

Parameter	Type	Required	Default Value	Description
options.email	string	false	Value set during `init`.	Email used to pre-fill the email field in login or sign up or form.
options.backTo	string	false	Value set during `init`.	A redirection URL for redirecting a guest back to during the following condition: Guest click on `Back to [App Name]` button in any Moneytree screens. Refuse to give consent to access permission in the consent screen. Logout from Moneytree via an app with this client id Revoke an app from settings screen opened via an app with this client id NOTE: No `Back to [App Name]` button will be shown if this value is not set, and any of the actions mentioned above will redirect the guest back to login screen by default.
options.authAction	`login`, `signup`	false	Value set during `init`. OR `login`	Show login or sign up screen when a session do not exists during an `authorize` call.
options.showAuthToggle	boolean	false	Value set during `init`. OR `true`	If you wish to disable the login to sign up form toggle button and vice-versa in the auth screen, set this to `false`.
options.showRememberMe	boolean	false	Value set during `init`. OR `true`	If you wish to disable the `Stayed login for 30 days` checkbox in the login screen, set this to `false`.
options.isNewTab	boolean	false	Value set during `init`. OR `false`	Call method and open/render in a new browser tab, default to same tab.
options.sdk_platform (private)	string	false	Generated by the SDK.	NOTE: this is for Moneytree internal use, please do not use it to avoid unintended behavior! Indicating sdk platform.
options.sdk_version (private)	semver	false	Generated by the SDK.	NOTE: this is for Moneytree internal use, please do not use it to avoid unintended behavior! Indicating sdk version.

Theming

We support gray labelling some of the services offered by Moneytree, please contact your Moneytree representative for more information.

Currently supported services:

onboard API
Vault service
Link-Kit service

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Installation

Usage:

Typscript

Polyfills

API

init

Usage:

authorize

Usage:

onboard

Usage:

exchangeToken

Usage:

tokenInfo

Usage:

logout

Usage:

openService

Usage:

requestMagicLink

Usage:

Common API options

Theming

Files

README.md

Latest commit

History

README.md

File metadata and controls

Installation

Usage:

Typscript

Polyfills

API

init

Usage:

authorize

Usage:

onboard

Usage:

exchangeToken

Usage:

tokenInfo

Usage:

logout

Usage:

openService

Usage:

requestMagicLink

Usage:

Common API options

Theming