Sessions Overview

Before accounts can be synchronized, a session must first be created. Sessions are created by passing a member's credentials, which are then authenticated. MDX On Demand supports two credential schemes: userkey, and login and password pair.

Credentials

Userkey

A userkey is a constant, unique authentication key which you assign to the member through the MDX Real Time API.

MX recommends the userkey be a 64 character alpha-numeric string containing no human-readable content. You may choose a different length if needed. A userkey can only ever be set or updated by you, the data provider, and cannot be updated by the user at any time.

Login and Password

Login and password match a user's online banking login and password. They can be provided by the user or assigned to the member through the MDX Real Time API during the user setup process.

The login and password should become invalid if a user changes their online banking credentials. When this occurs, account synchronization will be suspended until the values are updated by the user or by you through the MDX Real Time API.

Session Key

If the credentials are successfully authenticated, a session key is returned.

The session key is a unique, 64-character alpha-numeric string used to identify an authenticated session, and will be passed with all future requests from MX. The key should be valid for a minimum of 10 minutes or until a full account synchronization has been completed.

Multifactor Authentication

You may optionally choose to implement multifactor authentication (MFA). When MFA is implemented, the create session endpoint must return one or more challenges that must be answered before account synchronization can continue.

An MFA response will contain one or more challenges. Each challenge is made up of an id and a question and may also contain a list of options for multiple-choice answers. Once the user provides the answers to the questions, the session will be updated using the update session endpoint. You should then respond with the session key, another MFA challenge if needed, or an error.

If a response to an MFA question is incorrect, the session should be invalidated and a 401 (Unauthorized) error should be returned. This ensures correct credentials must be provided for any further communication.

Encrypting Credentials

You may optionally choose to have MX encrypt user-provided credentials using RSA 2048 public/private key pair.

Credentials that are provided by a partner via the MDX Real Time create member or update member requests are assumed to already be encrypted by our partner. When MX makes an MDX On Demand request to retrieve a user's account and transaction information, the credentials that were provided for that user will be used in the request exactly as they were received.

A user can provide their own login and password credentials to establish additional connections to an institution. If you have chosen to use the optional RSA 2048 encryption, it will be used to encrypt the user-provided credentials in the MDX On Demand request. The partner would then use their own private key to decrypt the credentials when establishing an MDX session.

The public key should be provided to MX in PEM format during your initial integration. Keys are environment-specific, so one key may be used in the integration environment and another in the production environment.