Skip to main content
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 to authenticate the user. MX recommends using a persistent value for the userkey, which can be any valid UTF-8 string that doesn’t contain human-readable content. A userkey can only ever be set or updated by you, not the user.

​
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 string used to identify an authenticated session, and is passed in a header with all future requests from MX within that session. The key should be valid for a minimum of 15 minutes or until a full account synchronization has been completed. To generate and manage session keys without having to store them in your system, follow these steps:
  1. After validating the userkey, create a string or key:value array containing the userkey (or an alternate value if needed) and a timestamp.
  2. Encrypt the string with an alphanumeric or Base64-encoded value and send it to MX as the session key.
  3. Upon receiving the session key in subsequent requests, decrypt it and validate that the timestamp is recent (such as within 15 minutes) to ensure it will expire.
  4. Extract the userkey (or alternate identifier) from the decrypted key and use it to retrieve the account data.

​
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 contains 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 is 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, invalidate the session and return a 401 Unauthorized error to ensure correct credentials are 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 you provide via the MDX Real Time create member or update member requests are assumed to have already been encrypted. When MX makes an MDX On Demand request to retrieve a user’s account and transaction information, the provided user credentials are 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’re using the optional RSA 2048 encryption, this is what’s used to encrypt the user-provided credentials in the MDX On Demand request. You then use your own private key to decrypt the credentials when establishing an MDX session. You should have already provided the public key to MX in PEM format during your initial integration. Keys are environment specific, which means one key may be used in the integration environment and another in the production environment.