Architecture and Security

The MX Platform API is a powerful, fully-featured API designed to make aggregating and enhancing financial data easy and reliable. It can seamlessly connect your app or website to tens of thousands of financial institutions.

The MX API is built around a standard REST architecture, uses predictable, resource-oriented URLs, and returns all data in JSON format. Requests are made with HTTP methods and HTTP response codes indicate the success or failure of those requests.

API Architecture and Resource Structure

The MX Platform API has many different resources and features, but once you break it down, it is centered around five major resource types. Virtually all the others are connected in one way or another with the resources described here.

Resource	Description
institution	An institution represents a financial institution (FI) like Chase or Wells Fargo. It’s important to point out that many real-world FI will actually have several different institution objects within the MX Platform API. This is because, for example, the mortgage division of Wells Fargo might use a separate system than its everyday banking division, which is different from its credit card division, etc.
user	A user represents an end-user accessing the MX Platform API via your application, be it a mobile app, web app, desktop app, etc.
member	A member represents the relationship between a user and an institution. A user may have multiple members, one each for their bank, their mortgage broker, their credit card provider, etc. Aggregation, verification, and many other processes are centered around a member, meaning this is probably the most important type of object you’ll be working with.
account	An account represents a financial account held by an FI, e.g., a user’s checking or savings account. A member may have more than one account associated with it. For instance, a user may have both a checking and savings account associated with one Chase login and would therefore have two accounts associated with that member.
transaction	A transaction represents any instance in which money moves into or out of an account, such as a purchase at a business, a payroll deposit, a transfer from one account to another, an ATM withdrawal, etc. Each transaction belongs to only one account.

Development and Production Environments

MX provides two environments: Production and development (also called integrations or INT). The development environment shares the same code base and provides the same features as the production environment so that clients can properly develop and test their integrations. However, the development environment does not perfectly replicate the performance of the production environment nor the number and quality of connections to real-world institutions that can be found in the production environment. The development environment provides only the limited number of connections necessary for development testing. Furthermore, certain features — like OAuth — can only be tested in the development environment using MX-provided institutions, and no real-world institutions are available.

MX uses separate base URLs for its development and production environments. All examples given in this reference use the development base URL.

Development URL

_10

https://int-api.mx.com

Production URL

_10

https://api.mx.com

Authentication and Security

MX Platform API requests must use HTTPS with TLSv1.2 encryption or higher or else they will fail.

Requests also require basic access authentication where your client_id is the username and your api_key is the password. These values are available on the client dashboard.

Technically, basic access authorization requires the Base64 encoding of these values separated by a colon, but many HTTP clients will handle the encoding for you. For instance, all cURL example requests in this documentation use the -u option, e.g., -u client_id:api_key. Nevertheless, there is an example of Base64 encoding to the right.

Because the values described above may grant access to some or all of your data, you must keep them secret and keep them safe. Do not share them in public areas, use them in client-side code, or otherwise use them in a way that may compromise their security.

In some instances, requests that require authentication will return 404 Not Found, instead of 401 Unauthorized. This is to prevent leaking private information.

Basic authorization value

_10

Base64 encoding of:

_10

client_id:api_key

Example

_10

CLIENT-1234:API-KEY-4567 -> Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3

IP Whitelisting

All requests must come from a whitelisted IP address, which is configured via the client dashboard. Any request from a non-whitelisted IP address will return a 403 Forbidden error. IP addresses outside of the United States are normally not permissible, so any requests for non-US IPs will require additional scrutiny and will be manually investigated and approved. Should we have any questions or need further details, MX will contact you via email.

MX IP Address Ranges

MX maintains multiple data centers for failover and load balancing purposes. Each data center has a range of IP addresses and any IP address in these ranges can be active.

The DNS entries for the MX Platform API URLs can resolve to any IP address in our ranges and can change at any time. If you choose to whitelist the IP addresses that the API URLs are allowed to resolve to you must whitelist all of the IP address ranges.

CIDR	Range
64.77.254.32/27	30 addresses from 64.77.254.33 to 64.77.254.62
68.142.151.128/26	62 addresses from 68.142.151.129 to 68.142.151.190
97.75.178.32/27	30 addresses from 97.75.178.33 to 97.75.178.62
192.41.25.128/26	62 addresses from 192.41.25.129 to 192.41.25.190
192.41.58.128/26	62 addresses from 192.41.58.129 to 192.41.58.190

DDoS Protection

MX provides an on-demand DDoS protection service using Akamai's DDoS scrubbing center. In the event of a DDoS attack, traffic is only redirected to Akamai.

We will only redirect inbound requests (requests coming into MX), while outbound requests (requests sent to clients/partners) will still come from the existing IP ranges. Outbound requests include but are not limited to mobile upstream events, webhooks and aggregation requests.

Although we only redirect inbound requests, if you have firewall rules that prevent outbound connections to whitelisted IP addresses, you must add those to avoid service disruption during a DDoS mitigation event.

Visit Akamai's documentation to learn more about the IP addresses that may be used in the event of a DDOS attack: https://techdocs.akamai.com/origin-ip-acl/docs/update-your-origin-server. We suggest you subscribe to this page to stay up to date on any changes.

Limits on the API

Aggregation throttling

Standard aggregation jobs are throttled, and a new standard agg can only be started after the throttle period has elapsed. The default throttle period is three hours (10,800 seconds), though this limit can vary from one institution to another.

However, premium aggregation-type jobs won’t start the throttle period (extended history, identification, verification, statements, balance check). In other words, running a standard agg will always start the throttle period and prevent a new standard agg. Running any other type of job will not start the throttle period.

Premium aggregation-type jobs are never throttled. That is, you can run an account verification right after a standard agg (or balance request, or verification etc.). However, because standard aggs are throttled, you should generally use the include_transactions parameter on premium jobs if standard data is also required; this will prevent delays.

Throttled jobs will not return an error; the response will return with 202 Accepted and will contain the current state of the member, including the latest connection_status.

Jobs for members that have experienced credential-related errors won’t be throttled (connection_status: REJECTED, PREVENTED, UPDATED).

Balance jobs are limited to 5 requests every 2 hours.

There is no throttling of any kind when using the MX Bank test institution.

Data availability

Be aware that aggregation is not guaranteed to return all relevant information or even every data point on a given resource. For instance, aggregation may return the balance of an account, but return a null value for the apr and apy fields. This is to be expected in all resources and all aggregations.

User and member limits

The development environment limits developers to 100 users and access to only some of the top financial institutions.

No user may have more than 25 members in either the development or production environments.

Caching

Certain API resources are subject to change at any time; for instance, institutions. For this reason, we discourage you from caching lists of resources. If caching is necessary, we recommend refreshing a cached list at least daily.

Versioning

We always try to make API changes backwards-compatible. However, when we make breaking changes to the MX Platform API, we’ll increment the version number. The current version is v1. Versions are specified in a request’s Accept header. All requests will access the current version unless a different version is specified with the request, so it’s best to always specify the API version. The current Accept header is application/vnd.mx.api.v1+json.

OAuth

MX encourages partners to use OAuth for authenticating with financial institutions. However, some institutions support OAuth, while others don’t. And some institutions only support OAuth and no other forms of authentication.

Furthermore, using OAuth requires you to register with institutions that support OAuth to ensure security and trustworthiness. This registration can only be done after MX has granted you production access; MX will handle this registration on your behalf. You can request production access and OAuth registration on the dashboard.

If you have production access but have not yet been registered with the institutions that support OAuth, these institutions will not be returned in any institution-related endpoints.

This also means that there is only one OAuth institution available in the integration environment: mx_bank_oauth. You’ll have to use this for all OAuth development and testing in the integration environment.