Overview

OAuth provides a more secure connection for clients and their customers. As a token-based solution, credentials are handled entirely by the OAuth provider and exchanged for a token that MX can use.

In order to connect accounts via OAuth, the user will need to be directed to the OAuth provider’s site for authentication and authorization. Once the user has successfully authenticated, they will be redirected back to MX and then to the client app. This may introduce changes to how your integration works.

API implementations

Clients using the API to connect users will need to create the OAuth member, generate an OAuth URL for that member, send the user to that URL, and get the user back to their app.

Connect widget implementations

Clients utilizing the Connect widget in a desktop or mobile browser should not have to make any additional implementation changes.

WebView implementations, however, will need to send the user to the OAuth URL and configure a scheme to get the user back to their app.

OAuth in Atrium

Members

A member represents the relationship between a user and an institution, and creating one is how you connect one to the other. Thus, multiple members may be attached to a single user, e.g., one for their bank, another for their mortgage provider, another for their credit card provider, etc.

Member fields

Connection status definitions

Create member

This endpoint allows you to create a new member.

Calling the create member endpoint with is_oauth set to true allows you to create a member without having to include the institution’s required credentials in your request. The member will be created with a connection status of PENDING and a redirect URI will be provided in the oauth_window_uri field. Making a request to this URI will then take the user to the registered OAuth application where they can provide credentials and choose what data to share with MX. After completing the OAuth process, the connection status will be updated.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "member":{
          "institution_code":"chase",
          "metadata": "Additional information",
          "is_oauth": true
        }
      }'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "member": {
    "aggregated_at": "2016-10-13T17:57:36+00:00",
    "connection_status": "PENDING",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": true,
    "metadata": "Additional information",
    "name": "Chase Bank",
    "oauth_window_uri": "https://dev-firefly1.moneydesktop.com/oauth/predirect_to/MBR-7aa13bdb-2866-ba38-b326-d9fb32268f9b/lk76038j23cAstpxnt4g58vybqZqg9vnn0lz29bwmvc40tss5rhjxlyf53pns05vfd99y5m766fdj7njpf615A5j3013xmdqA9mwz5nAgs9gr2887h0krh1l4gbAxfp8ztnpd47wk6j2ztjbz1f0lyr73nbxft0pwjwkqdjnfpA8ktn9tbvAbxqn40645vs4kxxcAx2rjc0vyxhtfhsk5vpq3Anrmdjtfj8qlpc617bkntbAwlpylfqf4AshyvA6lpmn5ptrzqhd933k98rzymzmjgqy9m25np0fqm7zw6Akr8qyy5ckb6wxxA31vfjw5xm7td8z6vh7d0djwsgw34Awvj58psh2l7xk9414",
    "status": null,
    "successfully_aggregated_at": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

Example request with optional OAuth parameters

1
2
3
4
5
6
7
8
9
10
11
12
13
14
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "member":{
          "institution_code":"chase",
          "metadata": "Additional information",
          "is_oauth": true
        },
        "referral_source": "APP",
        "ui_message_webview_url_scheme": "yourapp"
      }'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "member": {
    "aggregated_at": "2016-10-13T17:57:36+00:00",
    "connection_status": "PENDING",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": true,
    "metadata": "Additional information",
    "name": "Chase Bank",
    "oauth_window_uri": "https://dev-firefly1.moneydesktop.com/oauth/predirect_to/MBR-7aa13bdb-2866-ba38-b326-d9fb32268f9b/lk76038j23cAstpxnt4g58vybqZqg9vnn0lz29bwmvc40tss5rhjxlyf53pns05vfd99y5m766fdj7njpf615A5j3013xmdqA9mwz5nAgs9gr2887h0krh1l4gbAxfp8ztnpd47wk6j2ztjbz1f0lyr73nbxft0pwjwkqdjnfpA8ktn9tbvAbxqn40645vs4kxxcAx2rjc0vyxhtfhsk5vpq3Anrmdjtfj8qlpc617bkntbAwlpylfqf4AshyvA6lpmn5ptrzqhd933k98rzymzmjgqy9m25np0fqm7zw6Akr8qyy5ckb6wxxA31vfjw5xm7td8z6vh7d0djwsgw34Awvj58psh2l7xk9414?referral_source=APP&ui_message_webview_url_scheme=yourapp",
    "status": null,
    "successfully_aggregated_at": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

Generate OAuth window URI

This endpoint will generate an oauth_window_uri for the specified member.

Generating a new oauth_window_uri is necessary in order to send the end user through the OAuth process again. There are several situations where you might want to do this. Below are a few examples:

• A previous attempt at OAuth failed — for instance if the end user closed the OAuth window before completing the process.
• The financial institution has revoked a previous OAuth token or the token has expired.

The member in question must be connected to an institution which supports OAuth. if the institution does not support OAuth, a 400 Bad Request error will be returned with the message Member cannot use OAuth.

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/oauth_window_uri' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "member": {
    "aggregated_at": "2016-10-13T18:07:57+00:00",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
    "name": "Chase Bank",
    "oauth_window_uri": "https://dev-firefly1.moneydesktop.com/oauth/predirect_to/MBR-b5f96507-4c9f-492d-8bb0-810bbe2b8c13/zz9A0dsm36n744jtAApwl7pgpyZApchszmv05jzA2x3bv3j73bfp00g1nszk3nh77zn9jg1vgqt95hsp2r5r1v5lspt7w9fsyqpfy7h902vb41b9b83l01jhbn23lAzvjqggs52pmgx40f41vjxkylp68jh8zl2l33mlzww83xq9dmm9fs0l7t6hfAdls1xmn26ph2xtdxtx3kg8thbkpnxwnd67mlxnqsjqfAjAfjgAzz5zdbsfqqz2hf4dl5v5h2Ax7kx1gz7wmnk7sfk5xtvvptj4r1vqn1wl92dzg0tAzxyvg75d6A3gwpA98pb4s3d1c0nw3zq0mfjdkgsxp7ppgl9x7qvv97n81d53",
    "status": "COMPLETED",
    "successfully_aggregated_at": "2016-10-13T17:57:38+00:00",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"    
  }
}

Step by step guide for creating an OAuth member

1. Search for an institution

Verify that supports_oauth: true is in the response.

Example request

1
2
3
4
$ curl -i 'https://vestibule.mx.com/institutions/mxbank' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
{
  "institution": {
    "code": "mxbank",
    "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
    "name": "MX Bank",
    "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
    "supports_account_identification": true,
    "supports_account_verification": true,
    "supports_oauth": true,
    "url": "https://www.mx.com"
  }
}

2. List users

Example request

1
2
3
4
5
6
7
8
# Here, we're checking to see what users are available for testing.
# Note that this endpoint returns paginated results and accepts optional pagination parameters.

$ curl -i 'https://vestibule.mx.com/users' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "users": [
    {
      "guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
      "identifier": "unique_id",
      "is_disabled": false,
      "metadata": "{\"first_name\": \"Steven\"}"
    },
    {
      "guid": "USR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "identifier": "unique_id",
      "is_disabled": false,
      "metadata": "{\"first_name\": \"Barb\"}"
    }
  ]
}

3. Create a member

Example request

1
2
3
4
5
6
7
8
9
10
11
12
$ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}' \
  -d '{
        "member": {
          "institution_code": "chase",
          "is_oauth: true,
          "skip_aggregation": false
        }
      }'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "member": {
    "aggregated_at": null,
    "connection_status": "PENDING",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "identifier": null,
    "institution_code": "chase",
    "is_being_aggregated": false,
    "metadata": null,
    "name": "Chase Bank",
    "oauth_window_uri": "https://dev-firefly1.moneydesktop.com/oauth/predirect_to/MBR-b5f96507-4c9f-492d-8bb0-810bbe2b8c13/zz9A0dsm36n744jtAApwl7pgpyZApchszmv05jzA2x3bv3j73bfp00g1nszk3nh77zn9jg1vgqt95hsp2r5r1v5lspt7w9fsyqpfy7h902vb41b9b83l01jhbn23lAzvjqggs52pmgx40f41vjxkylp68jh8zl2l33mlzww83xq9dmm9fs0l7t6hfAdls1xmn26ph2xtdxtx3kg8thbkpnxwnd67mlxnqsjqfAjAfjgAzz5zdbsfqqz2hf4dl5v5h2Ax7kx1gz7wmnk7sfk5xtvvptj4r1vqn1wl92dzg0tAzxyvg75d6A3gwpA98pb4s3d1c0nw3zq0mfjdkgsxp7ppgl9x7qvv97n81d53"
    "successfully_aggregated_at": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

4. Redirect user to the registered OAuth Application

Open a browser window to the oauth_window_uri. The user will be taken to the institution’s registered OAuth application page. Here, the user can enter their credentials and choose what to share with MX.

Communicating with the OAuth window

When the user completes the process, the opened window will attempt to send a post message back to you via window.opener.postMessage. You can use this post message as a way to make flow decisions in your own app.

If the process was successful the post message will have the following payload:

{
  mx: true,
  type: "oauthComplete/success",
  metadata: {
    member_guid: "{member_guid}",
  }
}

At this point the Member will be authenticated and a Job will be started. You will want to continue polling the member until the job is finished.

If the user completed the process, but either rejected the terms or had an error in the process, the post message will be:

{
  mx: true,
  type: "oauthComplete/error",
  metadata: {
    member_guid: "{member_guid}",
    error_reason: "{error_reason}"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Open a new window to the oauth uri. Keep a handle to the opened window.
const oauthWindow = window.open(oauth_window_uri)

window.addEventListener('message', function(data) {
  if (data.type === 'oauthComplete/success') {
    /**
     * At this point you will want to keep polling the member until the job is
     * complete. But you can close the oauth window now.
     */
    if (oauthWindow) oauthWindow.close()
  } else if (data.type === 'oauthComplete/error') {
    /**
     * At this point the user either rejected the OAuth terms or something went
     * wrong with the redirect back to MX.
     */
    if (oauthWindow) oauthWindow.close()
  }
})

Using OAuth in Connect with WebViews

There are three configuration options WebViews will need in order to have the optimal OAuth flow:

• is_mobile_webview: true — Allows the widget to know if it is in a WebView context.
• ui_message_version: 4 — Allows the widget to send new postMessage events.
• ui_message_webview_url_scheme: <your app> — Determines message scheme; this is is used by MX to redirect the user back to the client app in mobile contexts.

In-depth configuration documentation can be found here.

In-depth documentation on postMessages can be found here.

Example request

1
2
3
4
5
6
curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
  -H 'Accept: application/vnd.mx.atrium.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'MX-API-Key: {mx_api_key}' \
  -H 'MX-Client-ID: {mx_client_id}'
  -d '{ "is_mobile_webview": true, "ui_message_version": 4, "ui_message_webview_url_scheme": "{app scheme}" }'

Redirecting the user

Since the MX WebView can’t reliably send the user from the app to the OAuth provider’s site in a native browser, the containing iOS or Android app will need to. To facilitate this, your app will need to react to the connect/oauthRequested postMessage request:

<ui_message_webview_url_scheme>://connect/oauthRequested?metadata=...

The OAuth URL is inside of the metadata query parameter under the url key.

Example redirect with Java:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
/**
 * This Client will capture urls from MX and cancel them. It will specifically
 * handle the oauthRequested URL. You will want to set this client as your
 * WebView's client or add this functionality to your own.
 */
public class MXWebViewClient extends WebViewClient {
    private Activity activity;

    public MXWebViewClient(Activity mainActivity) {
        activity = mainActivity;
    }

    @Override
    public boolean shouldOverrideUrlLoading(WebView view, String url) {
        // Ensure you are looking for schemes from both 'mx', 'atrium' and whatever you configured
        // ui_message_webview_url_scheme to be. In this example, it was 'appscheme'.
        boolean isFromMX = url.startsWith("mx://")  || url.startsWith("atrium://") || url.startsWith("appscheme://");

        if (isFromMX) {
            try {
                Uri mxURI = Uri.parse(url);

                // Handle the oauth url redirect. Send the user to the URL given.
                if (mxURI.getPath().equals("/oauthRequested")) {
                    JSONObject mxMetaData = new JSONObject(mxURI.getQueryParameter("metadata"));
                    String oauthURL = mxMetaData.getString("url");
                    Uri oauthPage = Uri.parse(oauthURL);
                    Intent intent = new Intent(Intent.ACTION_VIEW, oauthPage);
                    activity.startActivity(intent);
                }
            } catch (Exception err) {
                Log.e("sb: Error creating URI", err.getMessage());
            }
            return true;
        }

        return false;
    }
}

Example redirect with Swift:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
/**
 * Set up the WebView to capture URLs. You will want to cancel all urls from MX.
 */
class ViewController: UIViewController, WKNavigationDelegate {

    var webView: WKWebView!
    let appScheme = "appscheme://"
    let mxScheme = "mx://"
    let atriumScheme = "atrium://"

    func webView(_ webView: WKWebView,
                 decidePolicyFor navigationAction: WKNavigationAction,
                 decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {

        // Ensure you are looking for schemes from both 'mx', 'atrium', and whatever you configured
        // ui_message_webview_url_scheme to be. In this example, it was 'appscheme'.
        let url = navigationAction.request.url?.absoluteString
        let isFromMX = url?.hasPrefix(appScheme) == true || url?.hasPrefix(mxScheme) == true || url?.hasPrefix(atriumScheme) == true

        if isFromMX {
            let urlc = URLComponents(string: surl ?? "")
            let path = urlc?.path ?? ""
            // there is only one query parameter ("metadata")
            // so just grab the first one
            let metaDataQueryItem = urlc?.queryItems?.first

            if path == "/oauthRequested" {
                handleOauthRedirect(payload: metaDataQueryItem)
            }

            // Cancel request
            decisionHandler(.cancel)
            return
        }

        // Allow request
        decisionHandler(.allow)
    }

    /*
     * Handle the oauthRequested event. Parse out the OAuth URL from the event
     * and open Safari to that URL
     * NOTE: This code is somewhat optimistic, you'll want to add error handling
     * that makes sense for your app.
     */
    func handleOauthRedirect(payload: URLQueryItem?) {
        let metadataString = payload?.value ?? ""

        do {
            if let json = try JSONSerialization.jsonObject(with: Data(metadataString.utf8), options: []) as? [String: Any] {
                if let url = json["url"] as? String {
                    // open safari with the url from the json payload
                    UIApplication.shared.open(URL(string: url)!)
                }
            }
        } catch let error as NSError {
            print("Failed to parse payload: \(error.localizedDescription)")
        }
    }
}

Getting back to your app

Once the user completes the OAuth process, MX will send the user back to the client app via a URL scheme like so:

<ui_message_webview_url_scheme>://oauth_complete?status=<success|error>&member_guid=<guid>

This part is optional for OAuth, but highly recommended. If this is not set, the user will end on an MX page with a success or error message and will have to navigate back to your app manually. Make sure to pick a scheme that your app can respond to.

Testing with MX Bank

You will only be able to test OAuth flows in the integration environment with the MX Bank (OAuth).

See the testing docs for more detail