Skip to main content

Nexus API

Authentication and Security

Nexus is a proprietary specification for the RESTful exchange of data between MX and a partner. Nexus allows a partner to access information from the MX system.

The Nexus API is accessed on an individual user basis. An overview of the Nexus integration flow is available here. When a Nexus session is established, all information exchanged will be in the context of that user.

Nexus supports json encoding of the request and response bodies. xml encoding is not supported at this time.

Authenticating a User​

Obtaining a session token is a two-step process:

Step 1: Request an API token​

Request an API token using the read API token endpoint in the MX SSO API.

Step 2: Exchange an API Token for a Session Token​

A session token is obtained by sending a POST request to /sessions

The session token will be used in each request made for the user. It should be passed in an MD-SESSION-TOKEN HTTP header as shown below.

This session token is valid for 30 minutes from the time it was created. The 30 minute expiration counter is refreshed with each call.

If you send a request with an expired session token you'll receive an error code of 4011.


_10
MD-SESSION-TOKEN: de2uS4jEwSYN7W0eoF_ZiLJQ7rtQaDbA9NkCZr_U4gujctbMw_WZYz7u6q3NMDlTYYCSSR7O3ec1fOP2wArN0g

Base URLs​

All URL endpoints in Nexus have a base URL. The base URL will depend on the environment being addressed.

Integration Server (for initial integration testing)


_10
https://int-data.moneydesktop.com/

Production Server


_10
https://data.moneydesktop.com/

Data Encoding​

MX Technologies is committed to providing high-quality data to accommodate a wide range of scenarios. Due to the financial nature of our data, sometimes special characters such as ', <, >, ", and = will be found in string fields. For example, an account might be identified as Mortgage Loan <= 15 Years. We strongly recommend that clients sanitize and/or encode the output of our API, such as HTML encoding prior to rendering in a web view.

Deprecated fields and endpoints​

MX will sometimes deprecate a field in an object, or deprecate an entire endpoint. This is done when a new field or endpoint is superior to the deprecated one. A note will explain each item that is deprecated, with a recommendation of what to use in its place.

New partner integrations should avoid using deprecated items. MX will maintain the deprecated fields and endpoints to support existing integrations, but we do recommend that existing integrations also update to use the new processes when convenient.

Headers​

Accept Header​

All requests require an Accept header to specify the version and the encoding of the desired response body:

application/vnd.moneydesktop.v1+json is also supported for backward compatibility with existing integrations.


_10
Accept: application/vnd.mx.nexus.v1+json

Content-Type Header​

POST and PUT requests require a Content-Type header to specify the format of the request body.


_10
Content-Type: application/vnd.mx.nexus.v1+json

application/vnd.moneydesktop.v1+json and application/json is also supported for backward compatibility with existing integrations.

MX-Skip-Webhook header​

Partners who use MX's webhooks can prevent them from being triggered by sending the optional MX-Skip-Webhook header with a value of true. Webhooks will be delivered if the header is set to false or if it is omitted altogether.

This header works for create, update, and delete requests on the following resources:

  • Accounts
  • Budgets
  • Categories
  • Goals
  • Holdings
  • Members
  • Transactions

Pagination​

Requests to all list endpoints that return multiple transactions (e.g. list transactions) should specify the desired records_per_page. The supported range is from 10 to 1000. If the records_per_page parameter is not specified or is outside this range, a default of 25 records per page will be used.

The response for page one will contain a total_pages field. To retrieve the full set of transactions, subsequent requests should be made to the endpoint with the same date range and records_per_page values and with the page parameter set to the desired page.

Number Limits​

The limits for decimal numbers are described by their precision and scale (in the format "precision,scale"). Precision refers to the total number of digits. Scale refers to the number of digits to the right of the decimal. For example, 538.46's precision,scale is 5,2.

Security​

Requests must use TLS 1.2 (or higher) with known secure ciphers.

Sort Order​

Transactions returned from the List Transactions and List Account Transactions endpoints are sorted in this order: date (descending), id (ascending). Subsequent pages in multiple-page responses will continue with the same sort order.

Please note that the id field is a field internal to MX and not exposed in the Nexus API. It is used as the secondary sort to ensure the responses will always be ordered consistently.

Versioning​

We strive to make API changes backwards-compatible. When we make breaking changes we increment the version; therefore, it's best to specify the version of the API with each request. Versions are passed as part of the request's Accept header and Content-Type header.

Requests that don't specify a version will get the latest representation of resources, and unsupported endpoints will simply return a HTTP 404 NOT FOUND.

Enhancements within the current version MX continually makes enhancements to our APIs. Breaking changes are reserved for a new version, but non-breaking additions are regularly made in the current version. These include:

  • New fields added to existing objects (e.g., Adding currency_code to accounts).
  • New endpoints added (e.g., Adding List Holdings).
  • New processes: At times, MX will recommend a new process for accomplishing a task (e.g., Using List Member Credentials when updating a member). The new process is an improvement on the previous process and is recommended for all integrations, but MX will continue to support the old process throughout the current version of the API.

Partners should expect these enhancements to occur regularly. A new field in an object should not affect any existing integrations since nothing is being removed, but partners need to ensure their system can process or ignore new fields automatically. Partners should not rely on a fixed data model in any object.

Enhancements that will require a new version or advanced notice The following changes are breaking changes so they will only be made in a new version of the API, or with advanced notice to partners.

  • Removing a field from an object.
  • Changing the format of a field, or the contents it returns.
  • Removing an endpoint.
  • Adding a new Enumerated Value to a string that returns a fixed set of values (e.g., transaction status).
  • Major process changes (e.g., adding the requirement to use a new endpoint).

It is sometimes necessary to add new values to fields which return enumerators. Examples include account_subtype in the accounts model and field_type in the credentials model. Partner developers should allow for the addition of new enumerated values. MX will notify partners in advance when such additions are anticipated.

Sessionless Requests​

Sessionless Nexus requests are Atomic requests that work without the need for an MX session. They are particularly useful when you are making requests from the back end when the user is not present. All endpoints are available to be used this way. Nexus should be used either with sessions or sessionless, but not both. You will need to consult with MX before using sessionless Nexus.

Differences when using sessionless Nexus API requests:

  • You do not need to open a Nexus session.
    • Each individual request will contain the Client ID and User ID on the URL, information which is usually contained in the session token.
  • There is no automatic aggregation of a user's members.
  • A new MX-CLIENT-ACCESS-TOKEN header is used instead of the MD-SESSION-TOKEN header.
tip

Reminder: IP Whitelisting is required for sessionless Nexus.

Base URL​

For requests to the sessionless endpoints

EnvironmentURL
Integrationhttps://int-data.moneydesktop.com/clients/:client_id/users/:user_id/
Productionhttps://data.moneydesktop.com/clients/:client_id/users/:user_id/

The endpoint URI is added to the base URL. For example, a request to the list_accounts endpoint on INT would be:

https://int-data.moneydesktop.com/clients/:client_id/users/:user_id/accounts

All endpoints are available except the create_session endpoint (which is not needed).

info

Note that the client_id and user_id are the id values assigned to the client and user and NOT the internal MX GUID values such as USR-***. However, any GUID values used on the remainder of the URI will be internal MX GUIDs as documented for each endpoint.

Client access tokens​

A client access token must be passed with sessionless Nexus requests. Each token is valid only for a specific client on a specific MX environment. Client access tokens will be generated and provided by MX. There can be more than one token assigned to any specific client and they can be revoked individually if needed.

Headers​

Use the documented Content-Type and Accept headers. Do not use the MD-SESSION-TOKEN header. It is not needed with sessionless requests. Include a new MX-CLIENT-ACCESS-TOKEN header containing the Client access token.

Example request​

Here is an example request based on the following values:

  • Client ID is epicbank01
  • User ID is 12345
  • The supplied client access token is: 98765abcde43210
  • Endpoint is the List Members endpoint.

_10
curl -i https://int-data.moneydesktop.com/clients/epicbank01/users/12345/members \
_10
-H 'Accept: application/vnd.mx.nexus.v1+json' \
_10
-H 'MX-CLIENT-ACCESS-TOKEN: 98765abcde43210'

On this page