> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth in the Connect Widget

> Build a flow to connect users to their financial institutions using OAuth in the Connect Widget.

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](#browser-workflow)
* Mobile app using a WebView: See [Mobile (WebView)](#mobile-webview-workflow)
* Mobile app using an iframe inside a WebView: See [Mobile (iframe in a WebView)](#mobile-iframe-in-a-webview-workflow)

<Note>
  **NOT USING OUR CONNECT WIDGET?**

  If you're not using our Connect Widget, refer to our guide on [OAuth in Browsers](/resources/oauth-guide/oauth-in-browsers) or [OAuth in Mobile Apps](/resources/oauth-guide/oauth-in-mobile-apps).
</Note>

## Prerequisites

You must have registered for OAuth with the financial institution, unless you're using one of our test institutions. See [Registration](/resources/oauth-guide/#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.

1. Widget loads and user selects an OAuth-supported institution.
2. User selects **Go to log in**.
3. Widget opens the financial institution's OAuth window in the default browser.
4. User authenticates and selects data to share.
5. After authorization, users may see a brief redirect screen.
6. A connection status screen shows a loading indicator.
7. Once connected, and the user selects **Done**, [Member Connected, Primary Action Selected](/connect/widget-events#member-connected-primary-action-selected) widget event is sent.
8. 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.

<Warning>
  **WARNING**

  Do not open the OAuth window in a Webview. Some financial institutions have security restrictions for certain web containers or browsers. See [OAuth WebView Limitations](/resources/oauth-guide/#oauth-webview-limitations) for more information.
</Warning>

1. You send a widget URL request and set `is_mobile_webview` to `true` (sends widget events to `window.location` instead of `window.postMessage`).
2. Widget loads and user selects an OAuth-supported institution.
3. User selects **Go to log in**.
4. Widget triggers the [OAuth Requested](/connect/widget-events#oauth-requested) widget event.
5. Your app opens the OAuth URL (from the widget event in the previous step) in the default browser.
6. User authenticates and selects data to share.
7. User is redirected back to your app through either a custom URL or a custom scheme:
   * [Custom URL](#example---redirect-user-to-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](#example---redirect-user-using-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](/connect/widget-events#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}`.

<Accordion title="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                            |
</Accordion>

```bash theme={null}
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

<Note>
  **NOTE**

  If possible, we recommend using `client_redirect_url` rather than `ui_message_webview_url_scheme`.
</Note>

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`

<Accordion title="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                                          |
</Accordion>

```bash theme={null}
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)](#mobile-webview-workflow), 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](/connect/widget-events#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`.

<Note>
  **NOTE**

  If 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](/connect/widget-events#oauth-requested) widget event so your app can correctly open the OAuth window in the user agent.
</Note>

<CodeGroup>
  ```bash Request theme={null}
  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"
        }
      }'
  ```

  ```json Response theme={null}
  {
    "widget_url": {
      "type": "connect_widget",
      "url": "https://int-widgets.moneydesktop.com/md/connect/yxc...snip...Ay5",
      "user_id": "u-abc-789"
    }
  }
  ```
</CodeGroup>