OAuth in the Connect Widget - MX Documentation

This guide helps you build a flow to connect users to their financial institutions using OAuth, an industry-standard authorization protocol that allows users to connect their accounts without sharing credentials with your application. The OAuth implementation process varies based on how you’re embedding the widget:

Website using an iframe: See Browser
Mobile app using a WebView: See Mobile (WebView)
Mobile app using an iframe inside a WebView: See Mobile (iframe in a WebView)

NOT USING OUR CONNECT WIDGET?If you’re not using our Connect Widget, refer to our guide on OAuth in Browsers or OAuth in Mobile Apps.

Prerequisites

You must have registered for OAuth with the financial institution, unless you’re using one of our test institutions. See Registration for more info.

Browser Workflow

For browser integrations, the widget handles most of the OAuth flow automatically. You just need to capture a single widget event to know when to close the widget.

Widget loads and user selects an OAuth-supported institution.
User selects Go to log in.
Widget opens the financial institution’s OAuth window in the default browser.
User authenticates and selects data to share.
After authorization, users may see a brief redirect screen.
A connection status screen shows a loading indicator.
Once connected, and the user selects Done, Member Connected, Primary Action Selected widget event is sent.
You close the widget (unless you want the user to stay in the widget and connect more accounts).

To prevent issues, ensure you’ve set the widget URL request correctly and that:

is_mobile_webview is set to false or omitted
oauth_referral_source is set to "BROWSER" or omitted

Mobile (Webview) Workflow

When embedding the widget in a mobile app using a WebView, you must facilitate redirects to the OAuth provider and back to your app.

WARNINGDo not open the OAuth window in a Webview. Some financial institutions have security restrictions for certain web containers or browsers. See OAuth WebView Limitations for more information.

You send a widget URL request and set is_mobile_webview to true (sends widget events to window.location instead of window.postMessage).
Widget loads and user selects an OAuth-supported institution.
User selects Go to log in.
Widget triggers the OAuth Requested widget event.
Your app opens the OAuth URL (from the widget event in the previous step) in the default browser.
User authenticates and selects data to share.
User is redirected back to your app through either a custom URL or a custom scheme:
- Custom URL
  - End user is redirected to the URL set in the client_redirect_url request parameter that your app can respond to when linked from a browser.
  - oauth_referral_source must be set to "APP".
  - Once OAuth is complete, MX sends the user to the client_redirect_url with some additional query parameters that have information on what happened.
- Custom scheme
  - Sends widget events to the WebView via window.location = {scheme}://{event path}?metadata={json encoded metadata} instead of window.postMessage(eventObject).
  - Prevents the widget from automatically trying to open an OAuth window and instead sends the OAuth Requested widget event so your app can open the OAuth window in the user agent.

Example WebView Message

mx://connect/oauthRequested?metadata={...JSON encoded payload ...}

Example Redirect URL

https://widgets.moneydesktop.com/oauth/predirect_to/MBR-f1e7a927-924f-4b31-a8da-61de02954d74/4wa...snip...02?referral_source=BROWSER&skip_aggregation=false&

Example - Redirect User to Custom URL

Set the client_redirect_url parameter to specify where users are redirected after OAuth. MX appends query string parameters to the supplied client_redirect_url that describes what happened during OAuth: https://example.com?status={success|error}&member_guid={member_guid}&error_reason={error_reason} For example, if you set:

client_redirect_url: "https://example.com", the URL the user is sent to could be https://example.com?status=success&member_guid={MBR-XXX}
client_redirect_url: "https://example.com?state=mystate", the URL the user is sent to could be https://example.com?state=mystate&status=success&member_guid={MBR-XXX}.

Query string parameters

Name	Values	Type	Description
`status`	`success`: Continue showing the Connect Widget / `error`: Close the widget and show a generic error view	String	Indicates whether OAuth was successful
`member_guid`	`MBR-XXX`	String	Unique identifier for the created/updated member.
`error_reason`	`CANCELLED`: User cancelled the process / `DENIED`: User couldn’t authenticate with the provider / `IMPEDED`: User action required at provider website / `PROVIDER_ERROR`: Unknown provider error / `SERVER_ERROR`: Unknown error / `SESSION_ERROR`: Reauthentication failed using the existing session	String	Reason for OAuth error

curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \
    -H 'Accept: application/vnd.mx.api.v1+json' \
    -u 'client_id:api_key' \
    -H 'Content-Type: application/json' \
    -d '{
          "widget_url": {
              "widget_type": "connect_widget",
              "is_mobile_webview": true,
              "client_redirect_url": "{your_url_here}",
              "oauth_referral_source": "APP" 
          }
        }'

Example - Redirect User Using Custom Scheme

NOTEIf possible, we recommend using client_redirect_url rather than ui_message_webview_url_scheme.

Set the ui_message_webview_url_scheme parameter to specify a custom scheme for redirects after OAuth completion. The redirect URL will follow this format: yourAppScheme://oauth_complete?status={success|error}&member_guid={member_guid}&error_reason={error_reason}. This parameter also defines the scheme used for widget events. MX appends query string parameters to the supplied ui_message_webview_url_scheme that describes what happened during OAuth. For example:

If you set ui_message_webview_url_scheme: "yourAppScheme", the redirect URL might be: yourAppScheme://oauth_complete?status=success&member_guid=MBR-XXX
If you set ui_message_webview_url_scheme: "yourAppScheme?state=mystate", the redirect URL might be: yourAppScheme://oauth_complete?state=mystate&status=success&member_guid=MBR-XXX

Query string parameters

Name	Values	Type	Description
`status`	`success`: Continue showing the Connect Widget / `error`: Close the widget and show an appropriate error view	String	Indicates whether the OAuth process was successful
`member_guid`	`MBR-XXX`	String	Unique identifier for the `member` created or updated during OAuth
`error_reason`	`CANCELLED`: User cancelled the OAuth process / `DENIED`: User couldn’t authenticate with the provider / `IMPEDED`: User action required at provider website / `PROVIDER_ERROR`: Unknown provider error / `SERVER_ERROR`: Unknown error / `SESSION_ERROR`: Reauthentication failed using existing session	String	Reason for an OAuth error

curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \
    -H 'Accept: application/vnd.mx.api.v1+json' \
    -u 'client_id:api_key' \
    -H 'Content-Type: application/json' \
    -d '{
        "widget_url": {
            "widget_type": "connect_widget",
            "is_mobile_webview": true,
            "ui_message_webview_url_scheme": "yourAppScheme"
        }
    }'

Mobile (iframe in a WebView) Workflow

If you’re embedding the widget inside a mobile app using an iframe that’s embedded in a WebView, refer to Mobile (WebView), then consider the following:

After OAuth, do you need to redirect the user back to a native app? If so, you must set oauth_referral_source to APP, so at the end of OAuth the widget redirects the user to either the client_redirect_url or the ui_message_webview_url_scheme.
Do you want widget events to send to window.opener, a custom URL, or custom app scheme? To allow the Connect Widget to send widget events via postMessages:
1. Set is_mobile_webview to false.
2. Set oauth_referral_source to APP. This tells MX that you want us to redirect the user at the end of OAuth using the client_redirect_url you set, instead of using postMessages in a browser.
3. Listen for the OAuth Requested widget event in your webapp, then message the URL to your mobile app, so it can redirect the user via the mobile device’s browser. Once OAuth is completed, MX will redirect the user back to your client_redirect_url.

NOTEIf you set is_mobile_webview to true, the widget:

Sends widget events to the WebView via window.location = {scheme}://{event path}?metadata={json encoded metadata} instead of window.postMessage(eventObject).
Sets oauth_referral_source to APP, so the OAuth flow will redirect back to a native application instead of sending a postMessage to the opening window.
Won’t automatically try to open an OAuth window. Instead, it will send the OAuth Requested widget event so your app can correctly open the OAuth window in the user agent.

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "widget_url": {
        "widget_type": "connect_widget",
        "ui_message_version": 4,
        "client_redirect_url": "{your_url_here}",
        "oauth_referral_source": "APP"
      }
    }'

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxc...snip...Ay5",
    "user_id": "u-abc-789"
  }
}

​Prerequisites

​Browser Workflow

​Mobile (Webview) Workflow

​Example - Redirect User to Custom URL

​Example - Redirect User Using Custom Scheme

​Mobile (iframe in a WebView) Workflow

Prerequisites

Browser Workflow

Mobile (Webview) Workflow

Example - Redirect User to Custom URL

Example - Redirect User Using Custom Scheme

Mobile (iframe in a WebView) Workflow